文档开发者中心
我的
|

HarmonyOS 5

oh-package.json5 的 name 字段写成数字会编译报错

已解决
从其他项目拷贝过来的模块,编译时控制台刷了十几条错误,其中有一个问题是
收起
自动换行
深色代码主题
复制
The name of the 'entry' module must be a string, but received a value of type 'number'.

但是在oh-package.json5 看了"name": "entry" 确实是字符串,有人能知道是什么原因吗?

收起
自动换行
深色代码主题
复制
{
  "name": "entry",           
  "version": 1.0,        
  "description": "",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}
点赞
1
收藏
回复
14
分享
举报
浏览104 发布于2026-09-22 04:46北京
全部评论
最多点赞
最新发布
最早发布
|
采纳答复

开发者你好:

这个报错的根因不在 name 字段,而在 version 字段。你的配置中 "version": 1.0 写成了数字类型,而构建工具要求 version 字段必须是字符串类型。当 version 字段类型不正确时,构建工具在解析整个 oh-package.json5 文件时会出现异常,导致后续字段的类型校验逻辑错乱,从而报出了看似不相关的 name 字段类型错误,属于误导性的错误信息。

解决方案:

将 version 字段的值改为字符串类型即可解决。建议使用语义化版本号格式(如 "1.0.0"):

收起
自动换行
深色代码主题
复制
{

  "name": "entry",

  "version": "1.0.0",    // version 必须是字符串,且建议使用语义化版本号

  "description": "",

  "main": "",

  "author": "",

  "license": "",

  "dependencies": {}

}

修改后重新编译,十几条错误应该都会随之消失

14楼回复于2026-09-28 10:01 来自湖北

name: "entry" 没问题,明确写错的是 version: 1.0:版本号应使用字符串,建议改成:

收起
自动换行
深色代码主题
复制
"name": "entry",
"version": "1.0.0",

参考:官方报错说明、name / version 类型校验。

6楼回复于2026-09-22 06:22 来自广东

这个报错和你贴出来的 "name": "entry" 没关系。name 已经是字符串,真正的问题很可能是 version:

收起
自动换行
深色代码主题
复制
{
  "name": "entry",
  "version": 1.0
}

oh-package.json5 中 version 应该写成字符串,例如:

收起
自动换行
深色代码主题
复制
{
  "name": "entry",
  "version": "1.0.0",
  "description": "",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}

原因在于 JSON5 中:

收起
自动换行
深色代码主题
复制
"name": "entry"   → string
"version": 1.0    → number

虽然报错提示的是:

收起
自动换行
深色代码主题
复制
The name of the 'entry' module must be a string, but received a value of type 'number'.

但这类 oh-package.json5 校验报错容易让人误判具体字段。尤其是从其他项目复制模块后,建议把 oh-package.json5 的字段类型全部按照当前项目模板重新检查一遍。

另外,如果改成 "version": "1.0.0" 后仍然报同样错误,再重点检查 build-profile.json5、module.json5 以及项目根目录的 oh-package.json5,看是否存在类似:

收起
自动换行
深色代码主题
复制
{
  "name": 123
}

或者模块配置里把 entry 当成了数字。

你这个文件首先应该改成:

收起
自动换行
深色代码主题
复制
{
  "name": "entry",
  "version": "1.0.0",
  "description": "",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}

然后删除 .hvigor、build 等构建缓存重新编译。

不过仅从你贴出的这份文件来看,name 本身没有问题;version: 1.0 的类型确实值得先修正。

展开全部
11楼回复于2026-09-22 08:55 来自辽宁

version

版本号

必选

字符串

1.0.0

该模块构建产物(HAR/HSP)的版本号。

规范:采用X.Y.Z(主版本.次版本.修订号)三段式结构,遵循 semver 语义化规范,从1.0.0开始。

version 字段必须是字符串哦~~ 

4楼回复于2026-09-22 05:46 来自北京

这属于细节问题了,问题其实就在你贴出来的 oh-package.json5 里,但不是 name,而是这一行:

收起
自动换行
深色代码主题
复制
"version": 1.0

你把 version 写成了 number,而 oh-package.json5 中包版本号应该是 string。

改成:

收起
自动换行
深色代码主题
复制
{
  "name": "entry",
  "version": "1.0.0",
  "description": "",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}

也就是:

收起
自动换行
深色代码主题
复制
❌ "version": 1.0

✅ "version": "1.0.0"

为什么错误却提示 name?

这类 Hvigor / ohpm 配置校验错误有时候提示的位置并不直观,特别是从旧工程复制 Module 后,某个字段类型不符合 schema,后续解析可能产生一串级联错误。

你的:

收起
自动换行
深色代码主题
复制
"name": "entry"

本身确实是字符串,没有问题。

真正明显不符合规范的是:

收起
自动换行
深色代码主题
复制
"version": 1.0

JSON5 会把它解析成:

收起
自动换行
深色代码主题
复制
number

而不是:

收起
自动换行
深色代码主题
复制
string

并且版本号建议使用完整的语义化版本:

收起
自动换行
深色代码主题
复制
"1.0.0"

而不是:

收起
自动换行
深色代码主题
复制
"1.0"

如果改完仍然提示同样错误

因为你说这是从其他项目拷贝过来的 module,还建议继续检查另外几个配置文件:

收起
自动换行
深色代码主题
复制
工程根目录
├── build-profile.json5
├── oh-package.json5
│
└── entry/
    ├── build-profile.json5
    ├── oh-package.json5       ← 你现在这个
    └── src/main/module.json5

尤其检查 build-profile.json5 中:

收起
自动换行
深色代码主题
复制
{
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry"
    }
  ]
}

不要误写成:

收起
自动换行
深色代码主题
复制
{
  "modules": [
    {
      "name": 1,
      "srcPath": "./entry"
    }
  ]
}

因为你当前错误原文:

收起
自动换行
深色代码主题
复制
The name of the 'entry' module must be a string,
but received a value of type 'number'.

如果把 version 修正以后它仍然原样出现,下一优先级就是检查根目录 build-profile.json5 的 modules[].name,因为这条错误明确提到了 module name。

所以建议按这个顺序:

收起
自动换行
深色代码主题
复制
① entry/oh-package.json5
   "version": 1.0
        ↓
   "version": "1.0.0"

② 根 build-profile.json5
   modules[].name
        ↓
   必须是字符串

③ entry/build-profile.json5
   检查 product/buildOption 等字段类型

④ Sync Project / Clean
   ↓
   重新编译

你贴出来的文件里,name: "entry" 没错,version: 1.0 才是第一处应该修正的地方。

展开全部
13楼回复于2026-09-23 07:40 来自山西

先不要按报错文案只查当前模块的 name。"name": "entry" 是字符串,错误可能来自工程根目录、其他模块、依赖包里的另一份 oh-package.json5,也可能是缓存里仍引用旧配置。全文搜索所有 oh-package.json5 的 name,检查是否有未加引号的数字;同时留意 version 等字段类型,但不能把 version 错误直接等同于 name 错误。

用构建日志中的完整文件路径/模块路径定位是哪一个 entry,修正后重新解析依赖并构建;若仍出现,请贴完整错误上下文、根目录和模块级 oh-package.json5(隐藏私有仓库地址与令牌)。

12楼回复于2026-09-23 00:52 来自四川

楼上的结论方向是对的,但没把"为什么报错文案说的是 name"讲清楚,而这个点恰恰是这个问题最容易反复踩的地方,补几条。

一、报错文案里的 name 是"模块限定语",不是那个类型出错的字段

The name of the 'entry' module must be a string, but received a value of type 'number'. 这句里,'entry' 是 hvigor 聚合模块信息时用来标识"是哪个模块出的问题"的限定语;被判定为 number 的真实字段,是同一份 JSON5 里被解析成数值类型的那一个,也就是 version: 1.0。判断依据很直接:把 version 加上引号后这类错误全部消失,说明类型校验失败的字段就是它。所以别去改 oh-package.json5 的 "name": "entry",它本身没有错。

这里要理解一个 JSON5 的关键特性:它比 JSON 宽容得多,宽容点包括

  • 键可以不加引号(name: "entry" 合法)
  • 字符串可以用单引号
  • 允许注释、允许尾随逗号
  • 数字字面量的形式被放宽:允许 +1、0x1A、.5、5.、Infinity、NaN

所以 version: 1.0 在 JSON5 里是一个货真价实的 number 字面量,不是"看起来像版本号的字符串"。肉眼看到 1.0 和 "1.0" 差不多,解析器看到的类型完全不同,这就是问题的全部。

二、更危险的坑:别顺手把引号删掉写成 version: 1.0.0

很多人第一反应是"那就改成 1.0.0",如果写成 version: 1.0.0(不加引号),不再报"类型不对",而是直接抛 JSON5 解析失败——因为 1.0.0 不是合法的 JSON5 数值字面量(一个数字里不可能有两个小数点)。这类语法错误的报错位置经常落在文件末尾或下一行,比类型错误更难定位。正确写法只有一种:

收起
自动换行
深色代码主题
复制
{
  "name": "entry",
  "version": "1.0.0",          // 必须是带引号的字符串,且是 semver
  "description": "entry 模块",
  "main": "",
  "author": "",
  "license": "Apache-2.0",
  "dependencies": {
    "@ohos/library": "file:../library",   // 源码级本地依赖:指向含 oh-package.json5 的目录
    "somehar": "file:./libs/somehar.har", // 已构建产物依赖:指向 .har/.hsp 文件
    "lodash": "^4.17.21",                 // 中心仓依赖:semver 范围,允许升级到 4.x
    "dayjs": "1.11.10"                    // 中心仓依赖:精确锁定,不随上游升级
  }
}

三、用一条命令替代"肉眼检查",30 秒锁定类型问题

JSON5 的宽容特性决定了"看着像字符串"完全不可靠。工程根目录放一个 check.js,执行 node check.js,逐字段打印真实类型:

收起
自动换行
深色代码主题
复制
// check.js:逐个校验工程里所有 oh-package.json5 的 name / version 实际类型
const json5 = require('json5');
const fs = require('fs');
const path = require('path');

const targets = [
  './oh-package.json5',
  './entry/oh-package.json5',
  './library/oh-package.json5'
];

targets.forEach((p) => {
  if (!fs.existsSync(p)) {
    return;
  }
  const obj = json5.parse(fs.readFileSync(p, 'utf8'));
  console.log(p,
    '| name:', typeof obj.name, JSON.stringify(obj.name),
    '| version:', typeof obj.version, JSON.stringify(obj.version));
});

只要某一行打印出 version: number 1,那一行所在的文件就是根因所在。同样的思路也能查出 "name": 123 之类的非法包名。

四、name / version 的规则边界(这两条经常被混在一起讲)

1. name 必选、字符串,要符合包名规范:只允许小写字母、数字、-、_、.,不能以 . 或 _ 开头,不允许大写、空格、中文,多段包名用 @scope/name 形式。写成纯数字或者带大写字母,会在 sync / install 阶段被判定为非法包名(类似 The name ... is invalid)。纯数字在部分 hvigor 版本上还会被类型校验先拦一次,报出来就是"必须 string"。

2. version 必选、字符串,且要符合语义化版本:major.minor.patch。"1.0" 虽然是字符串,但不满足 semver,ohpm 在解析依赖、做版本比对或发布时会报错;"v1.0.0" 同样不被接受。建议一律写三位 "1.0.0"。

3. 空字符串字段(main、author、license)本身不报错,但 main 写成本地相对路径、或者留着 "main": "./Index.ets" 这种 npm 时代的写法,在 HAP 模块里属于误用,HAP 不需要入口文件字段。

五、概念澄清:oh-package.json5 的 name 和 module.json5 的 name 不是一回事

  • oh-package.json5 的 name 是包名,是 ohpm 视角下的包标识,用于 HAR/HSP 的构建产物命名、依赖解析与发布。
  • module.json5 里的 module.name 是模块名,和 build-profile.json5 的 modules[].name 对应,用于工程内的模块寻址。
  • 你这个工程里两者恰好都叫 entry,所以看起来像同一个字段,很容易在两个文件之间来回改却改不中。改 module.json5 修不好 oh-package.json5 的类型错误,反之亦然。

六、从别的项目拷贝工程时的高频连坐问题

你提到"从其他项目拷贝过来的模块,控制台刷了十几条错误",这类工程的报错通常是级联的:一个模块的 schema 校验失败,会让所有依赖它的模块跟着报错,所以数字会虚高。

1. 被引用的 HAR/HSP 子模块目录里各有自己的 oh-package.json5,很可能一起带着 version: 1.0 这种旧写法,要按"报错里的模块名"逐个定位,而不是只看根目录和 entry。

2. 用 grep -rn "version:[[:space:]]*[0-9]" --include=oh-package.json5 . 可以一次把所有未加引号的 version 捞出来。

3. 形如 "lodash": "^4.17.21" 的中心仓依赖,在换了机器/内网环境下会因为仓地址不同而解析失败,表现为 Cannot find module。先用 ohpm config get registry 确认仓地址是否正确,再考虑换私仓配置。

4. oh_modules、build、.hvigor、.idea 里可能残留旧工程的依赖树和缓存,改完 version 后如果错误还在,清掉这几个目录重新 sync 一次,别在脏缓存上判断问题是否修好了。

5. 在工程根目录执行 ohpm install --all,它会把所有模块的依赖关系重新解析一遍,报错会直接指出是哪个模块的哪一行(具体子命令以你本地 ohpm -h 的输出为准)。

七、结论

name 写成数字报错、但文件里 name 明明是字符串,绝大多数情况就是"文案错位 + JSON5 数值字面量"这两件事叠加:报错文案借用模块名做限定语,真正类型不对的是没加引号的 1.0。修的时候有三条底线:值一律加引号、version 一律补成三位 semver、改动前先用上面的脚本打印真实类型,别靠肉眼。另外提醒一句,这类 schema 校验发生在 hvigor 构建阶段,不是 TypeScript 类型检查,用 @ts-ignore、as any 之类的写法完全无效,也不要试图在 build-profile.json5 里绕过。

展开全部
10楼回复于2026-09-22 08:21 来自北京
报错指向 name,但你这份配置真正写错的是 version:1.0 是 number,而 oh-package.json5 要求版本号是字符串。 改成 "version": "1.0.0",再删除模块下的 oh_modules 与构建缓存后重新 ohpm install、编译。 同时检查工程根目录和该模块各自的 oh-package.json5,构建日志里的 entry 可能对应另一份同名模块配置,不一定是你当前打开的文件。 如果从旧项目复制过来,还要核对 name 是否和模块目录、build-profile.json5 中的模块名一致。 不要只改错误信息点名的 name;解析器遇到前面字段类型错误后,后续诊断可能出现连带误报。 官方资料: oh-package.json5 https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-oh-package-json5
9楼回复于2026-09-22 07:07 来自四川

【解决方案概述】
oh-package.json5 中 version 字段写成了数字类型 1.0,而非字符串类型 "1.0.0"。hvigor 在构建时对配置文件执行 Schema 校验,发现 version 字段类型不匹配后抛出类型错误,并引发后续十几条连锁报错。错误信息中提到的 "name" 是指模块属性名的通用提示,并非特指 "name" 字段本身,用户配置中 "name": "entry" 确实是字符串,没有问题。
【实施步骤】
步骤1:打开报错模块目录下的 oh-package.json5 文件
步骤2:将 "version": 1.0 修改为 "version": "1.0.0"(加引号,改为字符串类型)
步骤3:保存文件后,在 DevEco Studio 中执行 File > Sync and Refresh Project
步骤4:执行 Build > Clean Project 清除缓存,然后重新构建
【代码示例】
修改前:
{
  "name": "entry",
  "version": 1.0,
  "description": "",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}
修改后:
{
  "name": "entry",
  "version": "1.0.0",
  "description": "",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}
【参考文档】
- HarmonyOS oh-package.json5 配置文件说明:https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ohos-package-json5
【验证方法】
1. 修改 oh-package.json5 后执行 Sync and Refresh Project,确认无报错
2. 执行 Build > Build Hap(s)/APP(s) 重新编译,确认控制台不再出现 "must be a string, but received a value of type 'number'" 错误
3. 检查其余十几条连锁报错是否一并消失
【注意事项】
- 从其他项目拷贝模块时,需检查 oh-package.json5 中所有字段类型是否符合规范,version 必须为字符串类型
- 建议使用标准三段式语义化版本号(如 "1.0.0"),避免使用数字类型

 
展开全部
8楼回复于2026-09-22 06:51 来自广东
“name”:“entry”,“version”:1.0 ,第一行的name字符串是没有问题的,但是第二行的version字符串中的1.0没有采用字符串,添加引号,应改为“1.0.0”
7楼编辑于2026-09-22 06:42 来自山东
共2页
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。