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
        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

Loading

背景与目标

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

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

核心目标：

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

快速开始

安装

npm install minidev-buildconfig-cli

创建源配置

在项目根目录下按 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',
}

生成运行时配置

npx minidev-buildconfig generate --env dev

生成产物：

<miniprogramRoot>/generated/
  api.ts
  app.ts

业务代码使用

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"
  }
}

工作原理

命名规则

源文件	配置名	环境	生成文件
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 文件，提取配置名，加载环境配置，注入 env 字段，生成对应的 TypeScript 模块。

语言检测

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

生成文件契约

const config = {
  "env": "dev",
  "apiBaseUrl": "https://dev-api.example.com"
} as const

export type AppConfig = typeof config

export default config

• env 字段由 CLI 根据 --env 参数自动注入，源配置中无需重复声明 TypeScript 项目：

const config = { "env": "dev", "apiBaseUrl": "..." } as const
export type AppConfig = typeof config
export default config

JavaScript 项目：

const config = { "env": "dev", "apiBaseUrl": "..." }
module.exports = config

平台自动识别

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

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

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

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

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

CLI 参数

参数	必需	说明
--env <name>	是	目标环境名，例如 dev / stage / release
--cwd <path>	否	项目根目录，默认为当前目录
--platform <id>	否	平台标识：wechat / alipay / tt。多平台项目冲突时使用
--miniprogramRoot <path>	否	显式指定小程序源码根目录，覆盖平台自动识别
--output <path>	否	覆盖默认输出路径
--lang <ts|js>	否	指定输出语言。默认自动检测：检测到 app.ts 则输出 .ts，否则输出 .js

高级配置

package.json 覆盖

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

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

支持的字段：

• configDir — 自定义配置目录名（默认 configs）
• platform — 预置平台，避免每次指定 --platform
• miniprogramRoot — 显式指定 miniprogramRoot，跳过自动检测
• lang — 指定输出语言 "ts" 或 "js"，覆盖自动检测

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

推荐目录结构

微信项目：

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

支付宝项目：

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

自定义 configDir + miniprogramRoot：

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

常见问题

找不到配置文件

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

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

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

检测到多个平台

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

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

找不到 miniprogramRoot

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

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

设计理念：为什么用 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 命令，不改变业务代码，不上传非当前环境的配置内容。