疾风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": {}
}
小草飞上天开发者你好:
这个报错的根因不在 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": {}
}修改后重新编译,十几条错误应该都会随之消失
蓝瘦的蜕变
name: "entry" 没问题,明确写错的是 version: 1.0:版本号应使用字符串,建议改成:
"name": "entry",
"version": "1.0.0",
不羁的木木这个报错和你贴出来的 "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 的类型确实值得先修正。
华夏
| version | 版本号 | 必选 | 字符串 | 1.0.0 | 该模块构建产物(HAR/HSP)的版本号。 规范:采用X.Y.Z(主版本.次版本.修订号)三段式结构,遵循 semver 语义化规范,从1.0.0开始。 |
version 字段必须是字符串哦~~
飞b6这属于细节问题了,问题其实就在你贴出来的 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.0JSON5 会把它解析成:
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 才是第一处应该修正的地方。
橙动创意先不要按报错文案只查当前模块的 name。"name": "entry" 是字符串,错误可能来自工程根目录、其他模块、依赖包里的另一份 oh-package.json5,也可能是缓存里仍引用旧配置。全文搜索所有 oh-package.json5 的 name,检查是否有未加引号的数字;同时留意 version 等字段类型,但不能把 version 错误直接等同于 name 错误。
用构建日志中的完整文件路径/模块路径定位是哪一个 entry,修正后重新解析依赖并构建;若仍出现,请贴完整错误上下文、根目录和模块级 oh-package.json5(隐藏私有仓库地址与令牌)。
星桥似海楼上的结论方向是对的,但没把"为什么报错文案说的是 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 里绕过。
训犬者
开开心心每一天【解决方案概述】
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"),避免使用数字类型
Mandelx Hemen
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS 文件oh-package.json5中dependencies切换版本更新HAR对应的产物没有及时生效 (API12+)
HarmonyOS Flutter混编如何引用本地代码? (API12+)
HarmonyOS 编译报错“The certificate has expired!” (API12+)
HarmonyOS 编译报错00303168 (API12+)
HarmonyOS C++编译时char类型符号不一致导致项目移植逻辑异常 (API12+)
申请ohos.permission.DETECT_GESTURE后报错,提示名称无效。权限名必须使用SDK预定义的选项或在definePermissions中自定义的权限名称。
HarmonyOS JSON转换后数值类型被改变 (API12+)
HarmonyOS 客户端通过JS进行传参数,json字符串存在特殊字符转义问题导致的方法调用失败 (API12+)




































苏公安网备 32011402010933号