lucky_shop/stub-app-projects/mp-harmony/entry/README-HAR-DEPS.md

鸿蒙元服务 entry 模块依赖说明

⚠️ 本模块的 HAR 依赖必须保留，否则运行时会缺失子包 chunk（DIY 首页、商品分类、订单、营销页全部失效）。

背景

mp-harmony 项目把 uniapp 编译产物拆成 6 个鸿蒙模块：

模块名	srcPath	类型	内含
entry	./entry	主 HAP	入口页面、首页骨架、TabBar
components_diy	./ascf/ascf_build/components_diy	shared HAR	50+ diy-* 组件的 pack.js
pages_goods	./ascf/ascf_build/pages_goods	shared HAR	商品分类/详情/列表/购物车
pages_order	./ascf/ascf_build/pages_order	shared HAR	订单/支付/详情
pages_promotion	./ascf/ascf_build/pages_promotion	shared HAR	分销/积分/商户
pages_tool	./ascf/ascf_build/pages_tool	shared HAR	会员/支付/客服/工具页

entry 必须把这 5 个 HAR 加为依赖，否则运行时鸿蒙端加载 entry HAP 时找不到 components-diy/diy-group.pack.js 等子包 chunk，所有 diy 组件被 componentPlaceholder: view 替换成空 view，DIY 内容不显示，12s splash 兜底超时。

必须保留的依赖

entry/oh-package.json5 的 dependencies 必须包含：

{
  "components_diy":   "file:../ascf/ascf_build/components_diy",
  "pages_goods":      "file:../ascf/ascf_build/pages_goods",
  "pages_order":      "file:../ascf/ascf_build/pages_order",
  "pages_promotion":  "file:../ascf/ascf_build/pages_promotion",
  "pages_tool":       "file:../ascf/ascf_build/pages_tool",
}

防回归

# 检查 module.json + oh_modules + oh-package.json5 是否完整
node scripts/check-har-deps.js --rawfile

# 严格模式: 任何缺失即 exit 1 (CI 用)
node scripts/check-har-deps.js --rawfile --strict

校验脚本读取 ./har-deps-required.json5（白名单单一事实来源）。

如果你需要新增/删除子包

1. 修改 ascf_build/<新包>/oh-package.json5 的 name 字段
2. 在 mp-harmony/build-profile.json5 的 modules 数组里增/减模块
3. 在 entry/oh-package.json5 的 dependencies 里增/减 file: 依赖
4. 同步更新 entry/har-deps-required.json5 的 requiredHarDeps / ohModulesRoots
5. 在 DevEco Studio 中 Sync 项目 → 重新 Build → 运行 node scripts/check-har-deps.js --rawfile --strict
6. 通知 ascf 负责人对齐

常见误操作

• ❌ 在 DevEco 的 "Manage Dependencies" 对话框里只保留 @atomicservice/ascfapi → 5 个 file: 依赖会被清空，运行失败
• ❌ 删除 entry/oh-package.json5 的 file: 依赖后用 ohpm install 重装 → ohpm 会重新同步 file: 依赖，只要 file: 声明还在就是安全的
• ❌ 把 ascf_build/<pkg> 目录改名/移走 → file: 引用会变成 broken，运行失败

故障现象速查

现象	原因	修复
首页只显示 TabBar，无 DIY 内容	components_diy 缺失	加 file: 依赖 + Sync + Build
12s splash 后页面空白	任意一个 HAR 子包缺失	跑校验脚本看哪个缺失
商品分类页空白	pages_goods 缺失	同上
"Schema validate failed: must match pattern '^[a-zA-Z][0-9a-zA-Z_.]*$'... module.name"	vue.config.js 重新生成时把 pages_tool 的 module.json5.module.name 清空了	vue.config.js 已自动修复（_copyMpHarmonyBuild 末尾调用 fixSubpackageModuleNames）。如需手动跑：node -e "require('./vue.config.js').fixSubpackageModuleNames()"
"00604007 Field IS Empty Error: The name of package .../pages_tool cannot be empty" (DevEco 打开项目时 ohpm install 报)	pages_tool/oh-package.json5 的 top-level name 是空字符串	node scripts/fix-subpackage-module-names.js，会同时修 oh-package.json5 和 module.json5
"应用未关联服务空间" 报错	uniCloud 服务未关联（与本依赖无关）	uniCloud 目录右键关联服务空间

子包 module.name 容易丢失的原因

vue.config.js 重新生成鸿蒙元服务产物时，会重新输出 ascf_build/<pkg>/src/main/module.json5。 其中 module.name 字段如果模板里没正确读取 pkgName（或没设置），会被写成空串。

已自动化修复：

vue.config.js 暴露了 fixSubpackageModuleNames() 函数，会在以下场景自动触发：

1. 顶层副作用：vue.config.js 被任何入口 require 时（包括 HBuilderX 触发 vue-cli-service build）， 立即遍历 5 个子包，强制把 module.name 修正为包目录名。
2. 构建流程：mp-harmony 生产构建的 _copyMpHarmonyBuild() 末尾也会再调一次。

也就是说：只要 HBuilderX / 命令行 触发了 vue.config.js（构建必然触发），module.name 就被保证正确，无需任何手动操作。

手动调用方式：

# 直接跑独立脚本 (推荐)
node scripts/fix-subpackage-module-names.js

或者 require 模块（vue.config.js 内部用的就是这个）：

node -e "require('./scripts/fix-subpackage-module-names').fixSubpackageModuleNames()"

⚠️ 重要：vue.config.js 不再 export fixSubpackageModuleNames。历史教训：之前把 fixSubpackageModuleNames 放在 module.exports 上，vue-cli-service 校验 vue.config.js 导出的 keys 时会报：

Invalid options in vue.config.js: "fixSubpackageModuleNames" is not allowed

现在函数在独立模块里，vue.config.js 通过顶层 IIFE 调用它，导出干净。

输出示例：

🔧 [vue.config] 修正 ascf_build 子包 module.json5.module.name...
   ✅ components_diy: module.name "(空)" → "components_diy"
   ✅ pages_goods: module.name "(空)" → "pages_goods"
   ✅ pages_order: module.name "(空)" → "pages_order"
   ✅ pages_promotion: module.name "(空)" → "pages_promotion"
   ✅ pages_tool: module.name "(空)" → "pages_tool"
   📊 修正完成: 5 个子包被更新

校验脚本 check-har-deps.js 仍作为兜底防线，确保 module.name 不会再次被覆盖为空。

完整工作流（HBuilderX "发行" → "鸿蒙元服务"）：

1. HBuilderX 调 uniapp 编译器生成 unpackage/dist/build/.mp-harmony/
2. HBuilderX 调 vue-cli-service build → require('./vue.config.js')
3. 顶层 IIFE 触发 → 自动修复 5 个子包 module.json5.module.name
4. webpack 编译 → VersionInjectPlugin._copyMpHarmonyBuild() 拷产物到 ascf_src
5. 再次触发 fixSubpackageModuleNames()（防御性）
6. DevEco Studio 用 ascf_src 构建鸿蒙 HAP（此时 module.name 已正确）

手动修复（如需保留原 module.json5 内容但 name 字段错了）：

{
  "module": {
    "name": "<包目录名, 比如 pages_tool>",
    ...
  }
}

name 必须匹配 [a-zA-Z][0-9a-zA-Z_.]*（鸿蒙 schema 要求）。