minidev-buildconfig-cli

一个专为微信/支付宝/抖音小程序设计的多环境配置生成工具，遵循 Generated Config 模式：源配置经 CLI 生成运行时配置，业务代码始终依赖统一的生成入口，不直接引用环境文件。

flowchart LR
    subgraph Source["源配置 (configs/)"]
        direction TB
        A1["api.dev.json5"]
        A2["oss.dev.json5"]
        A3["app.dev.json5"]
    end

    subgraph CLI["minidev-buildconfig-cli"]
    end

    subgraph Output["生成产物 (generated/)"]
        direction TB
        C0["buildconfig.ts"]
        C1["api.ts"]
        C2["oss.ts"]
        C3["app.ts"]
    end

    subgraph App["业务代码"]
        direction TB
        D1["import apiConfig from './generated/api'"]
        D2["import ossConfig from './generated/oss'"]
    end

    Source --> CLI
    CLI --> Output
    Output --> App

1. 背景与目标

小程序项目通常需要多套环境（dev / stage / release），但微信、支付宝、抖音开发者工具采用直接上传流程，没有 webpack/vite 等构建环节，无法通过传统的构建时变量替换来处理环境差异。

常见做法是在代码中直接引入 dev.js / stage.js / release.js 等文件，发布前手动替换——这容易出错，且可能把非正式环境地址泄露到线上包。

核心目标：

• 源配置 configs/*.json5 按领域和环境分离，可读可维护
• CLI 一次命令生成所有运行时配置文件到 generated/ 目录
• 业务代码只 import generated/<name>，不关心当前环境
• 发布包中只存在当前环境配置，其他环境地址不会进入编译产物
• 兼容各平台 IDE 直接上传流程，不依赖额外构建工具链

2. 快速开始

2.1 安装

npm install [email protected]

2.2 创建源配置

在项目根目录下按 configs/<name>.<env>.json5 命名规则创建配置文件：

configs/
  api.dev.json5
  api.stage.json5
  api.release.json5
  app.dev.json5
  app.stage.json5
  app.release.json5

// configs/api.dev.json5
{
  apiBaseUrl: 'https://dev-api.example.com',
}

2.3 生成运行时配置

npx minidev-buildconfig generate --env dev

如果需要把项目根 package.json 的版本号也注入生成配置，通过 --pkg 指定要提取的字段：

npx minidev-buildconfig generate --env release --pkg version

如果需要注入构建编号（格式 YYYYMMDD.N，从中可解析出构建日期和当天构建次数），添加 --build 参数：

npx minidev-buildconfig generate --env release --build

也可以在 package.json 中固化配置，让每次构建都自动生成：

{
  "minidevBuildConfig": {
    "build": true
  }
}

生成产物：

<miniprogramRoot>/generated/
  buildconfig.ts   ← 包含 env 和可选的 version，项目级元数据的唯一来源
  api.ts
  app.ts

2.4 业务代码使用

import buildconfig from '../generated/buildconfig'
// buildconfig.env → 'dev'
// buildconfig.version → '1.0.0'  (仅当使用 --pkg version 时)
// buildconfig.build → '20260613.3'  (仅当使用 --build 时，当天第3次构建)

import apiConfig from '../generated/api'
// apiConfig.apiBaseUrl → 'https://dev-api.example.com'

推荐在 package.json 中添加脚本：

{
  "scripts": {
    "buildconfig:dev": "minidev-buildconfig generate --env dev",
    "buildconfig:release": "minidev-buildconfig generate --env release"
  }
}

3. 工作原理

3.1 命名规则

| 源文件 | 配置名 | 环境 | 生成文件 | |---|---|---|---| | configs/api.dev.json5 | api | dev | generated/api.ts | | configs/oss.stage.json5 | oss | stage | generated/oss.ts | | configs/app.release.json5 | app | release | generated/app.ts |

CLI 执行 --env dev 时自动扫描 configs/ 下所有 *.dev.json5 文件，提取配置名，按命名空间生成 TypeScript 模块。同时生成 buildconfig.ts 承载 env 和可选的 version、build 等构建级元数据。

3.2 语言检测

CLI 自动检测项目语言：检查 <miniprogramRoot>/app.ts 存在则输出 TypeScript，否则输出 JavaScript。也可通过 --lang 参数或 minidevBuildConfig.lang 显式指定。

3.3 模块格式检测（仅 JavaScript 输出）

当输出语言为 JavaScript 时，生成的 .js 文件可以是 CommonJS（module.exports）或 ESM（export default）语法，按以下优先级决定，遵循"约定大于配置"原则：

1. --format cjs|esm（CLI 显式参数）
2. minidevBuildConfig.format（package.json 中的显式配置）
3. 以上均未指定时，读取 package.json 标准的 "type" 字段："type": "module" → esm，缺失或其他值 → cjs。检测的 package.json 与 --pkg version 读取版本号时使用的是同一优先链：minidevBuildConfig.miniprogramPackagePath > <miniprogramRoot>/package.json > 项目根 package.json
4. 仍无法判断时，默认 cjs（与升级前行为保持一致）

TypeScript 输出不受此选项影响，恒定使用 export default 语法；生成文件的扩展名恒定为 .js，不会输出 .mjs（小程序运行时不支持）。

3.4 生成文件契约

buildconfig.ts（始终生成，承载构建级元数据）：

const config = {
  "env": "dev"
} as const

export type AppConfig = typeof config

export default config

传入 --pkg version 时，额外包含项目根 package.json 的版本号；传入 --build 时，额外包含构建编号：

const config = {
  "env": "release",
  "version": "0.2.0",
  "build": "20260613.3"
} as const

• env — 来自 CLI 必选参数 --env
• version — 仅在使用 --pkg version 时注入，读取自项目根 package.json.version
• build — 仅在使用 --build 或 minidevBuildConfig.build: true 时注入，格式 YYYYMMDD.N（N 从已生成的 buildconfig 文件中读取并自增，跨日自动重置为 1）

命名空间配置（如 api.ts、app.ts），仅包含源 .json5 中的字段：

TypeScript：

const config = { "apiBaseUrl": "https://dev-api.example.com" } as const
export type AppConfig = typeof config
export default config

JavaScript（cjs，默认）：

const config = { "apiBaseUrl": "https://dev-api.example.com" }
module.exports = config

JavaScript（esm，见 「3.3 模块格式检测」）：

const config = { "apiBaseUrl": "https://dev-api.example.com" }
export default config

env 和 version 仅存在于 buildconfig.ts 中，命名空间配置文件不再包含这些字段。需要时从 buildconfig 导入即可。

3.5 平台自动识别

CLI 按以下顺序自动检测小程序平台：

1. 微信 — 读取 project.config.json
2. 支付宝 — 读取 mini.project.json
3. 抖音 — 读取 project.tt.json

从平台配置文件中自动提取 miniprogramRoot，确定生成产物的输出根目录。

单平台项目直接运行即可，多平台项目（同时存在多个平台配置文件）需要显式指定：

minidev-buildconfig generate --env dev --platform wechat

4. CLI 参数

| 参数 | 必需 | 说明 | |---|---|---| | --env <name> | 是 | 目标环境名，例如 dev / stage / release | | --cwd <path> | 否 | 项目根目录，默认为当前目录 | | --platform <id> | 否 | 平台标识：wechat / alipay / tt。多平台项目冲突时使用 | | --miniprogramRoot <path> | 否 | 显式指定小程序源码根目录，覆盖平台自动识别 | | --output <path> | 否 | 指定输出目录，可重复传入多个（覆盖 minidevBuildConfig.outputs）| | --lang <ts\|js> | 否 | 指定输出语言。默认自动检测：检测到 app.ts 则输出 .ts，否则输出 .js | | --format <cjs\|esm> | 否 | 指定 JavaScript 输出的模块语法（仅在输出语言为 js 时生效）。默认按 「3.3 模块格式检测」 的优先级自动判断 | | --pkg <fields> | 否 | 从项目根 package.json 提取指定字段，写入 buildconfig.ts。支持逗号分隔（--pkg version,foo）和重复传入（--pkg version --pkg foo），可混用；当前支持 version | | --build | 否 | 注入构建编号到 buildconfig.ts，格式 YYYYMMDD.N（N 每次调用自增，跨日重置）。也可通过 minidevBuildConfig.build: true 固化 |

5. 高级配置

5.1 package.json 覆盖

当默认约定不满足时，可在 package.json 中配置 minidevBuildConfig：

{
  "minidevBuildConfig": {
    "configDir": "build-configs",
    "platform": "wechat",
    "miniprogramRoot": "app-overridden"
  }
}

支持的字段：

• configDir — 自定义配置目录名（默认 configs）
• platform — 预置平台，避免每次指定 --platform
• miniprogramRoot — 显式指定 miniprogramRoot，跳过自动检测
• lang — 指定输出语言 "ts" 或 "js"，覆盖自动检测
• format — 指定 JavaScript 输出的模块语法 "cjs" 或 "esm"，覆盖 package.json "type" 字段的自动检测（仅在输出语言为 js 时生效，详见 「3.3 模块格式检测」）
• build — 设为 true 时等同于每次构建都传入 --build 参数
• outputs — 指定一个或多个输出目录（路径相对项目根目录）。多目录场景下，所有产物同步写入每个目录，内容完全一致。CLI --output 优先级更高，会覆盖此配置而非合并

优先级：CLI 参数 > package.json > 平台自动检测

5.2 多输出目录（独立分包场景）

微信小程序独立分包（"independent": true）运行时与主包隔离，无法 require 主包文件。可通过 outputs 将产物同步写入多个目录，让独立分包直接就近导入：

{
  "minidevBuildConfig": {
    "outputs": ["src/generated", "src/subpackages/foo/generated"]
  }
}

或通过 CLI 参数指定：

minidev-buildconfig generate --env release \
  --output src/generated \
  --output src/subpackages/foo/generated

产物：

src/generated/buildconfig.js                    ← 主包导入
src/subpackages/foo/generated/buildconfig.js    ← 独立分包导入

同一次运行写入，两个目录内容完全一致。

5.3 推荐目录结构

微信项目：

project-root/
  configs/
    api.dev.json5
    app.release.json5
  miniprogram/
    app.ts
    generated/
      buildconfig.ts
      api.ts
      app.ts
  project.config.json
  package.json

支付宝项目：

project-root/
  configs/
    api.dev.json5
  src/                          ← 支付宝默认 miniprogramRoot
    app.ts
    generated/
      buildconfig.ts
      api.ts
  mini.project.json
  package.json

自定义 configDir + miniprogramRoot：

project-root/
  build-configs/
    api.dev.json5
  app-overridden/
    generated/
      buildconfig.ts
      api.ts
  package.json                  ← 配置 minidevBuildConfig
  project.config.json

6. 常见问题

6.1 找不到配置文件

确保配置文件名符合 <name>.<env>.json5 格式（如 api.dev.json5），而非 dev.json 或 dev.json5。

如果配置目录不是默认的 configs，在 package.json 中设置：

{ "minidevBuildConfig": { "configDir": "build-configs" } }

6.2 检测到多个平台

仓库同时存在微信、支付宝或抖音的平台配置文件时，需要显式指定平台：

minidev-buildconfig generate --env dev --platform wechat

6.3 找不到 miniprogramRoot

平台配置文件不存在或缺少 miniprogramRoot 字段时，在 package.json 中显式指定：

{ "minidevBuildConfig": { "miniprogramRoot": "miniprogram" } }

6.4 版本号读取优先级

使用 --pkg version 时，版本号读取优先级为：

1. minidevBuildConfig.miniprogramPackagePath（显式配置）
2. miniprogramRoot/package.json（自动检测）
3. 项目根 package.json（回退）

如果小程序代码有独立的 package.json，建议设置 miniprogramPackagePath 指向它，以获得更精确的版本管理：

{
  "minidevBuildConfig": {
    "miniprogramRoot": "miniprogram",
    "miniprogramPackagePath": "miniprogram/package.json"
  }
}

7. 设计理念：为什么用 Generated Config 而不是环境文件替换

传统的环境文件替换方案（env.dev.js / env.stage.js 互相替换）下，环境与文件一一对应，更换环境需要替换文件，容易误操作。

Generated Config 模式将 环境与文件解耦：

环境源 (json5/yaml/远程配置)
        ↓
    CLI 生成
        ↓
  generated/*.ts (统一出口)
        ↓
    业务代码

配置来源按领域拆分为多个文件（api.dev.json5、oss.dev.json5），生成的产物也按领域独立（generated/api.ts、generated/oss.ts），业务代码按需引入。切换环境只需重新运行 CLI 命令，不改变业务代码，不上传非当前环境的配置内容。