auto-control-miniprogram

v0.2.1

Published

a month ago

微信小程序 / 小游戏自动化工具：一行命令完成代码上传、生成体验版二维码、构建 miniprogram_npm 等流程，封装自官方 miniprogram-ci

Downloads

0High
0Medium
0Low

abinnpm

wechat weixin miniprogram minigame miniprogram-ci wxa ci qrcode preview upload auto-control 微信小程序小游戏二维码上传

Auto-Control-Miniprogram

微信小程序 / 小游戏自动化 CI 工具：一行命令完成代码上传、生成体验版二维码。封装自微信官方 miniprogram-ci，提供更易用的 CLI 与配置文件。

特性

✅ 一行命令：acmp preview 直接出二维码、acmp upload 直接上传开发版
✅ 终端 ASCII 二维码：扫码即体验，无需打开图片查看器
✅ 同时支持小程序和小游戏：通过 type 字段切换
✅ 自动构建：上传前自动跑你的 pnpm build / npm run build
✅ 配置文件友好：acmp.config.js 一处配置，CLI / 编程 API 共享
✅ 完整 TypeScript 类型：defineConfig 提供智能提示
✅ CI 友好：私钥支持文件路径或字符串注入（适合环境变量）

适用范围与能力边界

⚠️ 重要：自开发账号 vs 第三方平台账号是两套不同的能力

本工具基于 miniprogram-ci，面向自开发账号，能做的就是 miniprogram-ci 能做的：

| 功能 | 是否支持 | 说明 | | --- | --- | --- | | 上传开发版（upload） | ✅ | 上传到「开发版本」列表 | | 体验版二维码（preview） | ✅ | 终端 ASCII / 图片 / base64 任选 | | 构建 miniprogram_npm（packNpm） | ✅ | 小程序专用 | | 提交审核 | ❌ | 自开发账号无 API，只能在 mp 后台手动点 | | 发布 / 版本回退 / 撤回审核 / 分阶段发布 | ❌ | 同上，仅第三方平台 OpenAPI 支持 |

如果你需要全自动「写代码 → 提交审核 → 发布」，唯一路径是注册微信开放平台第三方平台并改造为代开发模式，那是另一套大工程，本工具不覆盖。

安装

# 推荐作为项目 devDependency
pnpm add -D auto-control-miniprogram
# 或
npm install -D auto-control-miniprogram
# 或
yarn add -D auto-control-miniprogram

一次性准备工作

1. 下载上传私钥

登录 mp.weixin.qq.com → 开发管理 → 开发设置 → 小程序代码上传 → 生成并下载 private.<appid>.key。下载到默认 ~/Downloads/ 即可，下一步 acmp init 会自动把它复制到 .keys/；也可以手动放到 .keys/。

2. 配置 IP 白名单

同样在 开发管理 → 开发设置 → 小程序代码上传 页面，把执行机器的公网出口 IP 加入白名单。

不知道自己 IP？跑 curl ifconfig.me，或第一次执行 acmp preview 时报错信息会直接告诉你 IP 是多少。

3. 一键初始化

在项目根目录运行：

npx acmp init

init 会一次性完成：

生成 acmp.config.js 模板（已存在则不覆盖）
创建 .keys/ 目录
自动从 ~/Downloads/ 复制 private.wx*.key 到 .keys/（找不到则提示手动放）
把 .keys/ 与 qrcode.jpg 追加到 .gitignore
往 package.json 注入两条脚本：ci:preview（生成图片二维码）、ci:upload

可选开关：

npx acmp init --no-copy-keys       # 不要从 ~/Downloads 自动复制私钥
npx acmp init --no-inject-scripts  # 不要往 package.json 写 scripts

完成后把 acmp.config.js 里的 appid 改成自己的即可。

使用

CLI

# 生成体验版二维码（终端 ASCII，默认）
npx acmp preview

# 改为输出图片到 ./qrcode.jpg
npx acmp preview --qr-format image

# 上传到「开发版本」列表
npx acmp upload --version 1.0.0 --desc "首次发布"

# 不要执行 build 步骤（沿用上次的产物）
npx acmp preview --no-build

# 指定配置文件
npx acmp preview --config ./build/acmp.config.js

# 构建 miniprogram_npm（小程序专用）
npx acmp pack-npm

acmp init 会默认往 package.json 注入这两条脚本，之后用包管理器跑即可：

pnpm ci:preview   # 等价于 acmp preview --qr-format image，每次执行直接覆盖 ./qrcode.jpg
pnpm ci:upload    # 上传到「开发版本」列表，需要追加 --version <ver> --desc <desc>

对应的 package.json 片段：

{
  "scripts": {
    "ci:preview": "acmp preview --qr-format image",
    "ci:upload": "acmp upload"
  }
}

编程式 API

import { preview, upload, defineConfig } from 'auto-control-miniprogram'

const config = defineConfig({
  appid: 'wxXXXXXXXX',
  type: 'miniProgram',
  projectPath: './dist',
  privateKeyPath: './.keys/private.wxXXXXXXXX.key',
  build: 'pnpm build',
})

await preview(config)
// 或
await upload(config, { version: '1.0.0', desc: '首次发布' })

config 也可以从环境变量装配（适合 CI）：

import { preview, defineConfig } from 'auto-control-miniprogram'

await preview(
  defineConfig({
    appid: process.env.WX_APPID!,
    privateKey: process.env.WX_PRIVATE_KEY,    // 私钥内容直接注入
    projectPath: './dist',
    build: false,                              // CI 流水线里独立做 build
  }),
)

配置项

acmp.config.js（也支持 .cjs / .mjs / .acmprc.json / package.json 的 acmp 字段）：

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | appid | string | — | 必填，小程序 / 小游戏 AppID | | type | 'miniProgram' \| 'miniGame' \| 'miniProgramPlugin' \| 'miniGamePlugin' | 'miniProgram' | 项目类型 | | projectPath | string | './dist' | 待上传代码目录 | | privateKeyPath | string | './.keys/private.<appid>.key' | 上传私钥文件路径 | | privateKey | string | — | 直接传私钥内容（与 privateKeyPath 二选一） | | ignores | string[] | ['node_modules/**/*'] | 忽略上传的文件 glob | | setting | CompileSetting | — | 编译设置（透传给 miniprogram-ci） | | build | string \| false | — | 上传前自动执行的命令；false 跳过 | | qrcodeFormat | 'terminal' \| 'image' \| 'base64' | 'terminal' | 二维码输出形式 | | qrcodeOutput | string | './qrcode.jpg' | 二维码图片路径（仅 image 格式） | | pagePath | string | '' | 预览的页面路径 | | searchQuery | string | '' | 预览页面的 query | | scene | number | — | 预览场景值 | | robot | number | 1 | 上传机器编号（1～30） |

CompileSetting 包含：es6 / es7 / minify / minifyJS / minifyWXML / minifyWXSS / codeProtect / autoPrefixWXSS / uploadWithSourceMap / disableUseStrict / ignoreUploadUnusedFiles。

完整示例

微信小程序

// acmp.config.js
/** @type {import('auto-control-miniprogram').AcmpConfig} */
module.exports = {
  appid: 'wxabc1234567890',
  type: 'miniProgram',
  projectPath: './dist',
  build: 'pnpm build',
  qrcodeFormat: 'terminal',
  setting: {
    es6: true,
    es7: true,
    minify: true,
    autoPrefixWXSS: true,
  },
}

微信小游戏

// acmp.config.js
/** @type {import('auto-control-miniprogram').AcmpConfig} */
module.exports = {
  appid: 'wxabc1234567890',
  type: 'miniGame',
  projectPath: './dist',
  build: 'pnpm build',
  qrcodeFormat: 'terminal',
  ignores: ['node_modules/**/*'],
}

更多示例见 examples/。

常见问题

`invalid ip: x.x.x.x`

执行机器的公网出口 IP 没在白名单里。去小程序后台「开发管理 → 开发设置 → 小程序代码上传」加上即可。换网络（WiFi 切换、热点、VPN）后 IP 会变，需要重新加。

二维码扫不开 / 显示「无权限」

扫码账号必须先在小程序后台「成员管理 → 体验成员」中加为体验者。

二维码扫了一会儿就过期

体验版二维码有效期 25 分钟，过期后重新跑 acmp preview 即可。

我已经 `acmp upload` 了，怎么提交审核 / 发布？

自开发账号没有提审 / 发布 API，需要登录 mp.weixin.qq.com → 管理 → 版本管理 → 开发版本 手动「提交审核」。审核通过后再点「发布」。

在 CI 上怎么用？

把私钥内容存到 CI Secret，然后通过 privateKey 字段注入：

import { upload, defineConfig } from 'auto-control-miniprogram'

await upload(
  defineConfig({
    appid: process.env.WX_APPID!,
    privateKey: process.env.WX_PRIVATE_KEY!,
    projectPath: './dist',
    build: false,
  }),
  { version: process.env.GIT_TAG!, desc: process.env.GIT_COMMIT_MESSAGE || '' },
)

CI 机器的出口 IP 同样要加进白名单。

配置文件能不能用 ESM / TypeScript？

支持 acmp.config.js / .cjs / .mjs，由 cosmiconfig 加载。TypeScript 配置文件目前需要先编译为 JS。

路线图

[ ] 子命令 acmp check：检查 IP / 私钥 / projectPath 等基础项
[ ] 子命令 acmp size：分析包体大小
[ ] 配置文件支持 .ts（jiti 加载）
[ ] 第三方平台代开发场景的可选支持

欢迎在 Issues 提建议。

贡献

参见 CONTRIBUTING.md。

致谢

微信团队的 miniprogram-ci — 一切上传 / 预览能力的底层来源
掘金 · 微信小程序 CI/CD 实践 — 早期方案参考

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme