@shuyun-ep-team/cem-module-replace

用于本地开发时替换 CEM 已融合产物中的三方小程序模块。

典型场景：三方工程热更新编译到 dist 后，使用本 CLI 读取并处理本地产物，再替换到 CEM 已融合产物 dist/modules/{appKey}，同时更新宿主 app.json、路由表与桥接入口。

推荐：免安装执行

npx -y --registry=https://registry.npmjs.org/ --package @shuyun-ep-team/cem-module-replace@latest cem-module-replace \
  --app-key health-aging-mini-program \
  --source ./dist \
  --dist ../tmp/v1/dist

推荐第三方项目使用免安装形式执行。npx 会临时拉取 @shuyun-ep-team/cem-module-replace，并执行包内暴露的 cem-module-replace 命令。

如果需要锁定版本：

npx -y --registry=https://registry.npmjs.org/ --package @shuyun-ep-team/[email protected] cem-module-replace \
  --app-key health-aging-mini-program \
  --source ./dist \
  --dist ../tmp/v1/dist

一次替换

npx -y --registry=https://registry.npmjs.org/ --package @shuyun-ep-team/cem-module-replace@latest cem-module-replace \
  --app-key health-aging-mini-program \
  --source ./dist \
  --dist ../tmp/v1/dist

监听替换

npx -y --registry=https://registry.npmjs.org/ --package @shuyun-ep-team/cem-module-replace@latest cem-module-replace \
  --app-key health-aging-mini-program \
  --source ./dist \
  --dist ../tmp/v1/dist \
  --watch

--watch 会先执行一次替换；之后监听 source 目录变化，按 --debounce 防抖并串行执行替换。某次替换失败会输出错误，但监听会继续保留，后续文件变化仍会再次触发替换。

可选：本地安装

如果希望把 CLI 固定到项目依赖中，也可以安装后执行：

pnpm add -D @shuyun-ep-team/cem-module-replace
npx cem-module-replace --app-key health-aging-mini-program --source ./dist --dist ../tmp/v1/dist

参数

| 参数 | 必填 | 默认值 | 说明 | | ------------ | ---- | ------- | ---------------------------------------------------------------- | | --app-key | 是 | - | 模块应用标识，用于替换到 dist/modules/{appKey}。 | | --source | 是 | - | 三方工程本地编译产物目录，例如 ./dist，必须是 build 模式产物。 | | --dist | 是 | - | CEM 已融合产物目录，目录下需要存在 app.js 与 app.json。 | | --watch | 否 | false | 启用监听模式，先替换一次，再监听 source 后续变化。 | | --debounce | 否 | 300 | 监听模式防抖时间，单位毫秒，必须是非负数字。 | | --verbose | 否 | false | 输出调试日志，包括参数解析、监听事件等信息。 |

注意：这里的模块产物必须是 build 模式构建出的产物，不要使用 dev / serve 模式的临时产物替换融合包，避免编译模式、环境变量、压缩和运行时代码形态与正式上传产物不一致。

本地 manifest

source 不需要提供 manifest.json。CLI 会读取 source/app.json，并仅从 app.json.pages 推导 manifest.pages；subPackages 或 subpackages 会参与运行时页面 id 冲突检测和模块处理，但不会写入 manifest.pages。本地替换版本固定为 local-dev。

常见错误

• source/app.json 不存在：--source 指向的目录内缺少 app.json。
• source/app.json 未声明 pages：app.json.pages 为空或不是字符串数组，CLI 无法推导本地 manifest。
• 页面 id 冲突：主包页面或分包页面的 basename 重复；请调整页面路径，保证页面 id 唯一。
• 未找到 MPX createApp 转 App 调用模式：模块 app.js 不是当前支持的 MPX createApp 编译产物形态，或压缩配置改写了 App 调用模式。
• dist/app.js 不存在 或 dist/app.json 不存在：--dist 不是完整的 CEM 已融合产物目录。
• 替换后微信开发者工具中没有生效：正常情况下 CLI 替换成功会刷新关键运行时文件时间戳；如仍未生效，请先确认终端已输出 replace once completed、目标 dist/modules/{appKey} 文件内容已更新、微信开发者工具无编译报错；最后再清空微信开发者工具缓存兜底。