mini-program-ng

mini-program-ng 是一个面向 Angular standalone 应用的微信小程序构建集成包。它通过 Angular CLI schematic 和 webpack 配置，把普通 Angular 应用补齐为可以输出微信小程序工程的项目。

当前包的目标不是替代 Angular CLI 的 Web 构建，而是在原有 Web 应用旁边增加一条小程序构建链路：

• Web 构建继续使用 ng build。
• 小程序构建使用 npm run build:mp，输出到 dist/mp。
• 初始化使用 ng add mini-program-ng 一步生成入口、配置、脚本和依赖。

适用范围

目前支持使用 bootstrapApplication(...) 启动的 Angular standalone 应用。

目标项目通常需要满足：

• Angular 版本与 mini-program-ng 的 peerDependencies 兼容。
• 应用入口使用 bootstrapApplication(App, appConfig) 或等价的 standalone 启动方式。
• 项目存在 angular.json、package.json、src/main.ts。
• 静态资源目录默认为 public/，也可以通过参数调整。

暂不覆盖复杂启动场景，例如 NgModule 启动、运行时动态选择根组件、默认导出根组件、复杂包装函数启动等。

一键集成

在目标 Angular 项目根目录执行：

ng add mini-program-ng

如果需要在初始化时写入真实小程序配置：

ng add mini-program-ng --appid wx1234567890abcdef --origin https://example.com --title MyApp

如果当前仓库内使用本地包测试，例如目标项目和 mini-program-ng 同在一个 monorepo：

ng add ../mini-program-ng --project mini-program-test2 --skip-confirmation

初始化完成后执行：

npm run build:mp

构建成功后，用微信开发者工具打开目标项目的：

dist/mp

开发监听模式：

npm run mp

ng add 会生成什么

执行 ng add mini-program-ng 后，目标项目会被写入这些内容：

| 文件或配置 | 作用 | | --- | --- | | src/mp.ts | 小程序入口。导出 createApp()，使用 createApplication() 创建 Angular 应用，并手动 bootstrap 根组件。 | | tsconfig.mp.json | 小程序专用 TypeScript 配置，供 @ngtools/webpack 编译 src/mp.ts。 | | build/miniprogram.config.js | 目标项目的小程序配置，包含 origin、标题、appid、静态资源复制规则等。 | | build/webpack.mp.config.js | 本地 webpack 配置入口。它会解析已安装的 mini-program-ng/dist/webpack.mp.config.js。 | | package.json scripts | 新增 mp 和 build:mp。 | | package.json devDependencies | 补齐 webpack、小程序构建、样式、Angular webpack 编译相关依赖。 |

生成后的脚本大致如下：

{
  "scripts": {
    "mp": "rimraf dist/mp/common dist/mp/pages dist/mp/app.js dist/mp/app.json dist/mp/app.wxss dist/mp/config.js dist/mp/project.config.json dist/mp/package.json dist/mp/package-lock.json && cross-env NODE_ENV=development isMiniprogram=true webpack --config build/webpack.mp.config.js --watch --progress",
    "build:mp": "rimraf dist/mp/common dist/mp/pages dist/mp/app.js dist/mp/app.json dist/mp/app.wxss dist/mp/config.js dist/mp/project.config.json dist/mp/package.json dist/mp/package-lock.json && cross-env NODE_ENV=production isMiniprogram=true webpack --config build/webpack.mp.config.js --progress"
  }
}

build/webpack.mp.config.js 会通过 require.resolve('mini-program-ng/package.json') 找到真实安装位置，所以可以同时适配普通 node_modules 安装和 npm workspace hoist 场景。

集成参数

ng add 支持这些参数：

| 参数 | 默认值 | 说明 | | --- | --- | --- | | --project | 第一个 application project | Angular 项目名。多项目 workspace 建议显式传入。 | | --appid | 空字符串 | 微信小程序 appid，会写入 project.config.json。生产项目建议传真实值。 | | --origin | https://test.miniprogram.com | 小程序路由 origin。生产项目建议改成业务域名。 | | --title | Angular project name | 小程序导航栏标题。 | | --miniprogramProjectName | Angular project name | 微信开发者工具项目名。 | | --publicDir | public | 静态资源目录，会复制到小程序产物。 | | --overwrite | false | 覆盖已生成文件和已有 mp / build:mp 脚本。 | | --skipInstall | false | 跳过 package manager install。 |

示例：

ng add mini-program-ng \
  --project mini-program-test2 \
  --appid wx1234567890abcdef \
  --origin https://example.com \
  --title "Mini Program Test"

构建产物

npm run build:mp 会生成：

dist/mp/
  app.js
  app.json
  app.wxss
  config.js
  project.config.json
  common/
  pages/
  miniprogram_npm/

其中 dist/mp 就是微信开发者工具需要打开的目录。

导入微信开发者工具

完成小程序构建后，按下面步骤导入微信开发者工具：

1. 在目标 Angular 项目根目录执行：

npm run build:mp

2. 打开微信开发者工具，选择导入项目。

3. 项目目录选择目标项目下的 dist/mp：

your-angular-project/dist/mp

不要选择 Angular 项目根目录，也不要选择 Web 构建目录 dist/<angular-project-name>。

4. AppID 填写 build/miniprogram.config.js 里的 projectConfig.appid。

如果初始化时已经传入：

ng add mini-program-ng --appid wx1234567890abcdef

这里会自动写入同一个 AppID。没有正式 AppID 时，可以先按微信开发者工具当前支持的测试号或无 AppID 方式导入，正式发布前再补真实 AppID。

5. 项目名称可以使用 build/miniprogram.config.js 里的 projectConfig.projectname，也可以在微信开发者工具里自定义。

6. 导入后点击编译，确认小程序可以正常启动。

后续开发时可以使用监听模式：

npm run mp

然后在微信开发者工具里重新编译或刷新预览。

与普通 Angular 构建的关系

mini-program-ng 不修改 Web 入口 src/main.ts，也不改变 ng build。

目标项目会拥有两条入口：

| 入口 | 使用场景 | | --- | --- | | src/main.ts | 浏览器 Web 应用，由 Angular CLI 构建。 | | src/mp.ts | 微信小程序应用，由 mini-program-ng 的 webpack 配置构建。 |

业务组件、路由、服务和 appConfig 可以继续共用。

本地开发这个包

在 mini-program-ng 包目录下构建：

npm run build

在同仓库的测试项目里使用本地包：

cd ../mini-program-test2
ng add ../mini-program-ng --project mini-program-test2 --skip-confirmation --overwrite
npm run build:mp

也可以先打包再安装：

cd ../mini-program-ng
npm pack
cd ../mini-program-test2
npm install -D ../mini-program-ng/mini-program-ng-2.0.5.tgz
npx ng generate mini-program-ng:init --project mini-program-test2 --overwrite
npm run build:mp

注意事项

• 生产项目请传入真实 --appid 和 --origin，不要沿用默认测试值。
• 如果目标项目已有 mp 或 build:mp 脚本，默认不会覆盖；需要覆盖时加 --overwrite。
• 如果目标项目不是 standalone bootstrapApplication(...) 启动，当前 schematic 可能无法自动推断根组件。
• src/mp.ts 会包含一些小程序环境下的 selector fallback 和启动日志，后续可以按生产需要收敛日志。
• 微信开发者工具打开的是 dist/mp，不是 Angular Web 构建目录。

当前验证结果

已在 mini-program-test2 上验证：

ng add ../mini-program-ng --project mini-program-test2 --skip-confirmation --overwrite
npm run build:mp
npm run build

两条构建均可通过，小程序产物生成到 dist/mp。