Mini Release

VS Code / Cursor 扩展：在侧栏 Mini Release 面板中完成微信小程序与抖音小程序的构建、版本号、CI 上传、预览二维码。本说明面向使用本插件的业务项目**，介绍如何安装、配置与排查问题。

功能概览

用于小程序多端框架（如Taro）的上传、预览。目前适配了微信小程序与抖音小程序。

能力	说明
发布面板	命令 `Mini Release: 打开发布面板`（`miniRelease.release`），选择构建环境、端（微信 / 抖音 / 双端）、版本策略、是否跳过构建、是否生成预览二维码
构建	按工作区 `.mini-release-config.json` 中的 `buildCommands` 执行（支持 `pnpm` / `npm` / `yarn` 或完整 shell）
上传	微信通过 `npx --yes miniprogram-ci` 执行官方 miniprogram-ci 的 `upload` CLI（见下文，不必在工程里单独装包）；抖音使用 `tt-ide-cli upload`（默认 `npx`，可用环境变量覆盖；可选测试通道 `--channel`）
预览	上传后可生成各端预览二维码；微信预览同样通过 `npx --yes miniprogram-ci preview`；启动页与 query 可来自缓存或环境变量

环境要求

编辑器：VS Code 1.85+（或与 package.json 中 engines.vscode 兼容的 Cursor 等）。
工作区：须用「打开文件夹」打开小程序仓库根目录；扩展以该根目录为工作目录解析配置并执行构建命令。
Node.js：本机已安装 Node；若 buildCommands 使用 pnpm / yarn，请自行安装对应工具。
微信：需在微信公众平台配置代码上传密钥（.key）；上传/预览通过 npm npx 调用 miniprogram-ci（见下节），需本机 Node.js + npm（PATH 中可执行 npx）。
抖音：需开放平台 AppSecret、CLI 免登 token（或写在配置 / project.tt.json）。

微信小程序 CLI（miniprogram-ci）

扩展不包含 miniprogram-ci 包体。微信上传与预览统一通过本机 npx 执行：

npx --yes miniprogram-ci upload …
npx --yes miniprogram-ci preview …

零工程依赖（默认）：若仓库未将 miniprogram-ci 列入 devDependencies，npx 会按需在 npm 缓存中拉取并运行（首次需能访问 npm registry，可能较慢）。
固定版本 / 离线优先（可选）：在工程根执行 pnpm add -D miniprogram-ci（或 npm i -D / 全局安装）后，同一工作区下 npx 会优先使用本地已安装的版本，减少拉取次数、便于锁版本。
包说明符（高级）：环境变量 MINIPROGRAM_CI_NPX_PACKAGE 可覆盖默认包名，例如 miniprogram-ci@2.1.31，用于 CI 或可复现构建。

环境要求：npx 须在 PATH 中可用（随 Node 官方安装包或 Volta / nvm 等工具链安装）。Windows 下扩展使用 npx.cmd 启动子进程。在 Cursor / VS Code 中若默认 npx 异常，扩展会净化子进程环境并优先使用 Homebrew / 常见路径下的 Node；仍失败时请用 MINIPROGRAM_CI_NPX_PATH（仅微信）或 MINI_RELEASE_PATH_PREPEND / MINIPROGRAM_CI_PATH_PREPEND（微信 + 抖音，见上表与「常见问题」）。

安装扩展

在 VS Code / Cursor：扩展 → ⋯ → 从 VSIX 安装…，选择获得的 mini-release-*.vsix 文件，按提示重载窗口。

使用步骤

打开文件夹：选择含 .mini-release-config.json 的仓库根目录。
打开面板：Cmd+Shift+P / Ctrl+Shift+P → 运行 Mini Release: 打开发布面板。
检查配置：若配置有误，面板会提示；修正后可在面板内刷新。
按向导操作：选择环境、端、版本与备注；含微信端时可填 CI 机器人（1–30，默认 1），含抖音端时可选择 上传通道（空或 1–4）。执行构建 → 上传 →（可选）预览。
查看日志：输出面板中选择 Mini Release 频道。

发布过程会在工作区根目录读写 .mini-release-cache.json（备注、分端版本号、预览启动参数、上传扩展参数等），一般无需手改。

配置说明

1. `.mini-release-config.json`（必填）

放在工作区根目录。缺少或 buildCommands 矩阵不完整时，面板会报错。

字段	类型	说明
`buildType`	`string[]`	启用的端：`weapp`、`tt` 的非空组合（可多选，勿重复）
`buildEnv`	`string[]`	环境名列表，须非空，如 `["daily","prod"]`，须与 `buildCommands` 键一致
`buildCommands`	`object`	构建命令映射，见下「构建命令矩阵」
`weappProjectPath`	`string`（可选）	微信配置查找基准路径，默认 `dist`；实际上传目录由 `project.config.json` 的 `miniprogramRoot` 决定
`ttProjectPath`	`string`（可选）	抖音配置根（须含 `project.tt.json`），默认 `.`
`weappAppSecret`	`string`（可选）	微信开放平台 AppSecret；低于环境变量，高于 `project.config.json`
`weappPrivateKeyPath`	`string`（可选）	微信代码上传密钥 `.key` 路径；同义字段 `wechatCiPrivateKeyPath`
`ttAppSecret`	`string`（可选）	抖音 AppSecret；低于环境变量，高于 `project.tt.json`
`ttUploadSecret`	`string`（可选）	抖音 CLI 免登 token；低于 `TT_CLI_TOKEN`，高于 `project.tt.json`

根目录工程文件（与 buildType 一致）：

启用 weapp：根目录须有 project.config.json。
启用 tt：根目录须有 project.tt.json（若实际工程在子目录，仍可用 ttProjectPath 指子目录，但根目录的 project.tt.json 校验以当前扩展逻辑为准）。

构建命令矩阵 `buildCommands`

键为 端:环境名，双端时可使用 all:环境名 一条命令代替两端分别写：

仅微信：weapp:daily、weapp:prod …
仅抖音：tt:daily、tt:prod …
双端：每个环境需 all:该环境，或同时有 weapp:该环境 与 tt:该环境。

值为 npm 脚本名（会自动加 pnpm run）、或以 pnpm/npm/yarn 开头的完整命令等。

示例：

    "buildEnv": ["daily", "pro"],
    "buildType": ["weapp", "tt"],
    "buildCommands": {
        "weapp:daily": "build:weapp:daily",
        "weapp:pro": "build:weapp:pro",
        "tt:daily": "build:tt:daily",
        "tt:pro": "build:tt:pro",
        "all:daily": "build:all:daily",
        "all:pro": "build:all:pro"
    },
    "weappAppSecret": "***",
    "weappPrivateKeyPath": "./private.***.key",
    "ttAppSecret": "***",
    "ttUploadSecret": "***"

2. 平台工程文件

project.config.json（微信）：appid、appSecret、miniprogramRoot、uploadSecret 等，见微信文档。

示例：

    "miniprogramRoot": "dist-weapp/",
    "appid": "***",
    "appSecret": "***",

project.tt.json（抖音）：与抖音小程序工程约定一致。

示例：

    "miniprogramRoot": "dist-tt/",
    "appid": "***",
    "appSecret": "***",

3. `.mini-release-cache.json`（自动生成）

扩展写入的缓存（备注、版本号、预览 path/query、构建产物类型等）；可加入 .gitignore，一般勿手改。

与上传相关的扩展字段（面板会读取并预填；在本次发布实际完成对应端上传后写回文件）：

JSON 键	说明
`weappCiRobot`	微信 miniprogram-ci CI 机器人编号，整数 1–30，默认 1。
`ttUploadChannel`	抖音 `tt-ide-cli upload --channel`，整数 1–4；不指定时通常不写该键。

仅发布微信时只更新/保留 weappCiRobot 一侧逻辑；仅发布抖音时更新 ttUploadChannel（选「默认」会清除缓存中的通道键）。与旧版单一 version 等字段的兼容逻辑不变。

环境变量参考

优先级：环境变量 > .mini-release-config.json > 工程 JSON。

微信

变量	说明
`MINIPROGRAM_CI_NPX_PACKAGE`	可选；`npx` 包说明符，默认 `miniprogram-ci`，可设为 `miniprogram-ci@x.y.z`
`MINIPROGRAM_CI_NPX_PATH`	可选；`npx` 可执行文件绝对路径（在 Cursor/VS Code 内若默认 `npx` 报 ENOENT 时，可在终端执行 `which npx` 后填此变量）
`MINI_RELEASE_PATH_PREPEND`	可选；在子进程 `PATH` 最前追加（与下行合并，本键优先）；微信与抖音凡经 `npx` 的子进程均生效
`MINIPROGRAM_CI_PATH_PREPEND`	可选；同上，与 `MINI_RELEASE_PATH_PREPEND` 二选一或同时配置（都会前置）
`WECHAT_APPID`	小程序 AppID
`WECHAT_SECRET` / `WECHAT_APPSECRET`	开放平台 AppSecret
`WECHAT_UPLOAD_SECRET` / `WECHAT_CI_PRIVATE_KEY_PATH` / `MINIPROGRAM_CI_PRIVATE_KEY_PATH`	代码上传密钥 `.key` 路径

预览（可选）：WECHAT_PREVIEW_PAGE_PATH、WECHAT_PREVIEW_QUERY、WECHAT_PREVIEW_DESC、WECHAT_PREVIEW_VERSION、WECHAT_CI_ROBOT（预览用的 miniprogram-ci robot）、WECHAT_PREVIEW_TIMEOUT_MS。

说明：微信上传使用的 CI 机器人以发布面板及缓存 weappCiRobot 为准（默认 1）；WECHAT_CI_ROBOT 仍主要作用于仅预览流程。

抖音

变量	说明
`TT_APPID`	小程序 AppID
`TT_SECRET` / `TT_APPSECRET`	开放平台 AppSecret
`TT_CLI_TOKEN`	`tt-ide-cli` 免登 token
`TT_CLI_COMMAND`	CLI 前缀，默认 `npx`（`set-app-config` / `upload` / `preview` 经 shell 调用时，与微信共用同一套 PATH 净化逻辑）

预览（可选）：TT_PREVIEW_MINIAPP_PATH、TT_PREVIEW_MINIAPP_QUERY、TT_QR_PAGE_PATH、MINI_RELEASE_TT_QR_URL、TT_PREVIEW_QR_URL。

系统

若 TMPDIR 异常，扩展可能将临时目录设为 ~/.mini-release-ci-tmp，避免 miniprogram-ci 在磁盘根目录写缓存失败。

常见问题

请先打开工作区文件夹：仅打开单个文件无法发布。
npx / miniprogram-ci 失败：确认本机已安装 Node、终端能执行 npx --yes miniprogram-ci --version；内网或离线环境请在工程内 pnpm add -D miniprogram-ci 或使用 MINIPROGRAM_CI_NPX_PACKAGE 指向可访问的 registry / 版本。
Cursor / VS Code 内 npm error ENOENT … Cursor.app/.../resources/lib：扩展宿主自带的 PATH 可能指向编辑器内置目录，npm 会解析失败（微信 miniprogram-ci 与抖音 tt-ide-cli 的 npx 调用均已对子进程做 PATH 净化并前置常见 Node 目录）。若仍报错：微信可设 MINIPROGRAM_CI_NPX_PATH（which npx）；微信与抖音均可设 MINI_RELEASE_PATH_PREPEND 或 MINIPROGRAM_CI_PATH_PREPEND 指向本机 Node 的 bin。
密钥 / AppID：对照上文优先级检查微信 .key 与 AppID、抖音 AppSecret 与 CLI token。
构建失败：确认 package.json 中存在 buildCommands 里引用的脚本，且本机命令与包管理器一致。
微信 CI 机器人 / 抖音上传通道：在面板「环境与构建」中填写；合法范围为微信 1–30、抖音 1–4 或留空；成功上传对应端后会写入 .mini-release-cache.json。
微信 / 抖音走 npx：依赖本机 npx；微信无工程内依赖时首次可能需联网下载 miniprogram-ci；抖音 tt-ide-cli 同理。

许可证

见工作区根目录 LICENSE 文件（非商业等约定）。

Mini Release

wanerwei

Mini Release

功能概览

环境要求

微信小程序 CLI（miniprogram-ci）

安装扩展

使用步骤

配置说明

1. .mini-release-config.json（必填）

构建命令矩阵 buildCommands

2. 平台工程文件

3. .mini-release-cache.json（自动生成）

环境变量参考

微信

抖音

系统

常见问题

许可证

1. `.mini-release-config.json`（必填）

构建命令矩阵 `buildCommands`

3. `.mini-release-cache.json`（自动生成）