weapp-vite 7.2.2 → 7.4.0

package/dist/docs/README.md

@@ -31,7 +31,7 @@
 - 🌐 **实验性 Web Runtime**：同一份原生 WXML/WXSS/TS 或 wevu Vue SFC 源码可通过 `-p web` 启动和构建浏览器版本
 - 🎨 **内置 Tailwind CSS**：通过 `weapp.tailwindcss` 配置 `weapp-tailwindcss` 的 core 与 generator 集成；Tailwind CSS v4 项目引入 `tailwindcss` 后可自动启用
 - 🧩 **实验性 uni-app 组件库兼容**：通过显式依赖白名单与 `WotUiResolver()` 在微信小程序和 Web 中使用 Wot UI Vue SFC
-- 🧰 **IDE 命令增强**：可直接透传 `weapp-ide-cli` 全量命令（`preview/upload/config/automator` 等）
+- 🧰 **IDE 命令增强**：通过 `wv ide <command>` 调用 `weapp-ide-cli`；保留旧顶层上传参数并提示未来弃用，SDK 与 IDE 边界见下文
 - 🧪 **真实产物单测**：`weapp-vite/test` 提供不启动 CLI 的程序化测试构建入口，可配合 `@mpcore/test` 测试页面和组件
 - 🌍 **内置 i18n**：构建期编译 locale JSON，通过 WXS 翻译模板，并在逻辑层安全切换已构建语言
 
@@ -64,6 +64,51 @@ wv build -p web
 
 `web` 是浏览器 runtime 的规范平台名，`h5` 仅作为向后兼容别名保留；未选择 Web 平台时不改变现有小程序构建。完整配置和兼容边界见 [Web 运行时配置](https://vite.weapp.dev/config/web) 与 [`@weapp-vite/web`](https://vite.weapp.dev/packages/web)。
 
+### Dashboard 嵌入 Vite DevTools
+
+`weapp-vite/dashboard` 是 Node 端共享核心；CLI 独立工作台与 Vite DevTools 复用同一个 `DevframeDefinition` 和 `@weapp-vite/dashboard` 面板。可选适配器位于 `weapp-vite/dashboard/vite`，使用官方 `createPluginFromDevframe`，不会由普通包入口或 CLI 自动加载。
+
+接入方安装 `@weapp-vite/dashboard`、`@vitejs/devtools` 和 `@vitejs/devtools-kit`。当前接入按 Vite `8.3.0`、DevTools / Kit `0.7.6`、Devframe `1.1.0` 验证；Kit 是可选 peer，宿主依赖不进入小程序产物。
+
+```ts
+import type { DevToolsConfig } from '@vitejs/devtools/config'
+import type { DashboardAnalyzeSnapshot, DashboardContentRoots } from 'weapp-vite/dashboard'
+import { DevTools } from '@vitejs/devtools'
+import { createAnalyzeDashboardDevframe, resolveDashboardClientAssets } from 'weapp-vite/dashboard'
+import { createAnalyzeDashboardPlugin } from 'weapp-vite/dashboard/vite'
+
+export function createDashboardHost(snapshot: DashboardAnalyzeSnapshot, roots: DashboardContentRoots) {
+  const dashboard = createAnalyzeDashboardDevframe({
+    snapshot,
+    roots,
+    clientAssets: resolveDashboardClientAssets(roots.projectRoot),
+  })
+  const hostOptions: DevToolsConfig = {
+    builtinDevTools: false,
+    clientAuth: true,
+    allowedOrigins: [],
+    mcp: false,
+  }
+  return {
+    dashboard,
+    plugins: [
+      DevTools(hostOptions),
+      createAnalyzeDashboardPlugin(dashboard, { base: '/tools/weapp/' }),
+    ],
+  }
+}
+```
+
+将返回的 `plugins` 交给 Vite 配置。调用方先完成分析及历史元数据持久化，用 `createDashboardArtifactSnapshot().capture` 收集该次分析的产物，再提交 `{ current, previous, artifacts }`。后续调用 `dashboard.update(result, artifacts, previousResult?)`；仅运行事件变化时调用 `dashboard.emitRuntimeEvents(events)`。提交后不要再修改报告或产物 Map。
+
+每个控制器只同时挂载到一个逻辑宿主。适配器记录成功安装的 Vite 配置身份，并仅在该配置拥有的环境关闭时释放核心。成功重启将所有权移交给新配置，旧实例和未安装的失败候选的清理都不会误释放当前控制器；替换前的资源校验失败时，旧宿主仍可查询和更新。首次 setup 失败或 SDK 安装开始后的失败会释放核心，不承诺回滚部分安装。自行使用 `dashboard.definition` 对接其他 Devframe 宿主时，调用方必须负责最终关闭和启动失败时的 `dashboard.dispose()`。核心不启动服务器，也不拥有外部宿主的认证、Origin 或 MCP 策略；共享宿主不是只读沙箱。
+
+DevTools `0.7.6` 自身存在程序化重启边界：重复使用同一个 `DevTools()` 返回值时，旧实例关闭可能同时关闭新实例的 WebSocket；不安装 Dashboard 也能复现。应在每次重载的 Vite 配置中重新调用 `DevTools()`，不要把该 SDK 插件实例长期缓存在复用的 inline 配置里。上述重启验证使用重新创建的 SDK 宿主和保留的 Dashboard 控制器，不代表修复了上游传输问题。
+
+面板默认位于 `/__weapp-vite/`，自定义目录与应用 `base` 独立。前端复用宿主连接或从页面相对位置发现元数据，复制视图链接保留目录和查询参数但排除认证 fragment。适配器只在开发模式挂载，生产构建不要求可选面板资源，也不导出报告。以上入口仅用于 Node 开发 / 构建宿主，不应导入小程序 AppService。
+
+仓库内可通过 `apps/dashboard-ui-lab` 的 `dev:inspector` 与 `dev:inspector:host` 验证两种宿主，详见其 [实验说明](../../apps/dashboard-ui-lab/README.md)。
+
 ### Vue 项目
 
 ```typescript
@@ -73,10 +118,10 @@ import { defineConfig } from 'weapp-vite/config'
 export default defineConfig({
   weapp: {
     srcRoot: 'src',
+    wxml: { remove: { comment: true } },
     vue: {
       enable: true,
       template: {
-        removeComments: true,
         htmlTagToWxml: true,
         htmlTagToWxmlTagClass: true,
       },
@@ -321,20 +366,58 @@ weapp-vite dev --open
 # o -> 重新打开当前 DevTools 项目
 ```
 
+## 六端构建并上传
+
+显式执行 `wv build --upload`，在本次构建成功并校验产物后上传，不重复构建。支持微信 `weapp`、支付宝 `alipay`、抖音 `tt`、小红书 `xhs`、京东 `jd`、百度 `swan`；只上传开发版本，不自动提审或正式上线。
+
+```sh
+wv build --upload --dry-run
+wv build --upload -p weapp
+
+# 独立 upload 命令仍支持多个小程序目标；all 在此表示六端
+wv upload --platform jd,swan
+wv upload --platform all --dry-run
+
+# 内置本地自动版本演练，不修改版本或锁文件
+wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
+```
+
+通常无需配置 `weapp.upload`：默认读取业务 `package.json.version`，说明自动生成 `项目名@版本`；默认不升版、不读取 Git、不运行 npm。需要覆盖时用 `weapp.upload` 或 CLI `--uv` / `--desc`；本地自动版本显式使用 CLI `--bump patch|minor|major` / `--git-desc`，分别与 `--uv` / `--desc` 冲突，不写入 Vite 配置。`.env.test` / `.env.production`、不同 AppID、本地自动版本与 CI 方案见[上传环境与自动版本](https://vite.weapp.dev/guide/upload/environments.html)。普通 `build`、`dev/HMR` 不上传，`preview` 不使用上传默认参数；配置文件仍正常求值。`build` 的上传专属参数必须与 `--upload` 一起使用，不支持 `--watch` 或 Web-only。
+
+自动元数据在首次配置求值、编译前准备一次，批量共用；升版仅处理命令根目录的应用清单，不向父目录查找。真实升版需要本机 npm，只有 Git 说明要求已有提交的 Git 仓库；不执行生命周期钩子、不 commit/tag/push。dry-run 不运行 npm、不修改版本或锁文件，直接导入 `package.json` 的构建代码仍读取原始版本。实际升版后的构建或上传失败不回滚，重试去掉 `--bump` 并复用原版本，必要时用 `--uv` / `--desc` 固定上一批元数据。
+
+`build -p all --upload` 保持“小程序 + Web”语义，等两个后端都构建成功后只上传小程序；独立 `wv upload -p all` 才是六端逐一构建上传，首次失败停止。`--dry-run` 只构建并校验产物，不校验凭据、不调用 SDK。
+
+多个平台可用一份 `weapp.multiPlatform.projectConfigs` 映射集中配置 AppID，公共字段用对象展开复用，不必手工维护六份原生 JSON。构建器在代码输出目录内生成对应项目配置；原生文件方式仍可使用。完整配置见[一份配置与批量上传](https://vite.weapp.dev/guide/upload.html#batch)。
+
+官方工具按目标安装，凭据只使用环境变量，不在 `weapp.upload` 中配置。完整的项目配置、AppID、凭据获取与环境文件、上传、预览、批量操作、CI 与排障见[小程序上传与预览指南](https://vite.weapp.dev/guide/upload.html)：[小红书](https://vite.weapp.dev/guide/upload/xhs.html)、[抖音](https://vite.weapp.dev/guide/upload/tt.html)、[微信](https://vite.weapp.dev/guide/upload/weapp.html)、[支付宝与淘宝边界](https://vite.weapp.dev/guide/upload/alipay.html)、[京东](https://vite.weapp.dev/guide/upload/jd.html)、[百度](https://vite.weapp.dev/guide/upload/swan.html)。本地速查见 `dist/docs/upload.md`；淘宝暂不支持，不要用 `-p alipay` 替代。
+
+## 六端构建并预览
+
+```sh
+wv preview -p tt --mode test
+wv preview -p xhs,jd,swan --mode production
+wv preview -p all --dry-run
+```
+
+`preview` 复用上述六端构建与凭据，调用官方预览接口，不上传开发版本、不提审、不正式发布。微信返回 `.weapp-vite/preview/` 下本次生成的二维码图片；支付宝、京东返回二维码图片 URL；抖音、小红书、百度返回官方预览链接。默认 mode 为 `production`，不要求上传版本，也不接受 `--uv`、`--bump` 或 `--git-desc`。百度预览也需要 `SWAN_MIN_VERSION`。
+
+`--dry-run` 只构建和校验产物，不调用 SDK、不生成预览结果。真实扫码权限与有效期依平台规则，详情见 [CLI 预览文档](https://vite.weapp.dev/guide/cli.html)。
+
 ## CLI 中调用 weapp-ide-cli
 
-`weapp-vite` 内置了对 `weapp-ide-cli` 的透传能力，除了 `dev/build/close/open/init/generate/analyze/npm/prepare/mcp` 等原生命令外，其它 IDE 相关命令都可以直接调用：
+`weapp-vite` 内置了对 `weapp-ide-cli` 的透传能力：原生命令通常优先，其他命令仅在 IDE catalog 命中时透传。`wv upload` 默认走六端 SDK，但保留带明确旧参数的顶层微信 IDE 上传；`wv preview` 仍是 SDK 预览，不属于旧语法兼容范围。稳定的显式 `ide upload`、`ide preview` 不弃用：
 
 ```sh
-weapp-vite preview --project ./dist/build/mp-weixin
-weapp-vite upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
+weapp-vite ide preview --project ./dist/build/mp-weixin
+weapp-vite ide upload --project ./dist/build/mp-weixin -v 1.0.0 -d "release"
 weapp-vite cache --clean compile
 weapp-vite cache --clean all
 weapp-vite config lang zh
 weapp-vite config set autoTrustProject true
 weapp-vite navigate pages/index/index --project ./dist/build/mp-weixin
 # 等价写法
-wv preview --project ./dist/build/mp-weixin
+wv ide preview --project ./dist/build/mp-weixin
 wv cache --clean all
 ```
 
@@ -349,6 +432,21 @@ weapp-vite ide logs --open
 wv ide preview --project ./dist/build/mp-weixin
 ```
 
+原有顶层上传的长、短参数仍可原样执行，不额外触发 weapp-vite 构建：
+
+```sh
+wv upload --project ./dist --version 1.2.3 --desc "release"
+wv upload -p ./dist -v 1.2.3 -d "release"
+```
+
+新 SDK 上传使用 `wv upload -p weapp` 即可，无需 `--project`，框架按项目配置与本轮实际输出自动定位。上面 `./dist` 只是旧 IDE 工程目录示例，应包含 `project.config.json`；旧入口省略定位参数时保持透传，不会默认补 `dist`。
+
+每次旧顶层调用只警告一次未来移除，不要求立即改写脚本；若只想保留 IDE 行为，改为 `wv ide upload -p ./dist -v 1.2.3 -d "release"`，该显式入口不警告。若迁移到 SDK，先在**源码项目根**安装 `miniprogram-ci`、配置 AppID、代码上传私钥与 IP 白名单，再执行 `wv build --upload -p weapp --uv 1.2.3 --desc "release"`。SDK 会重新构建、使用新凭据，不复用 IDE 登录；不要把旧 `--project` 的产物目录直接作为 `[root]`。
+
+`-p` 有 `--version/-v`、`--project`、`--appid`、`--ext-appid` 或 `--info-output/-i` 等旧标记时才表示 IDE 项目目录，否则表示平台，不猜测路径。旧标记与 SDK 的 `--platform`、`--uv`、`--bump`、`--git-desc`、`--dry-run`（含其 `--no-*` 形式）混用，在 IDE、编译或版本修改前报错；SDK dry-run/自动版本不适用于 IDE。`--desc` 共用，`-d` 只在旧调用中是说明，原生命令中仍是 debug。
+
+`wv upload --help` 查看 SDK 帮助；`wv help upload` 保留旧 IDE 帮助并提示未来弃用；`wv ide help upload` 不弃用、不警告。等号写法、选项值与 `--` 边界等完整规则见[旧上传兼容与迁移](https://vite.weapp.dev/guide/cli.html#legacy-upload)。
+
 ## CLI 启动 MCP
 
 `weapp-vite` 已集成 `@weapp-vite/mcp`：

package/dist/docs/getting-started.md

@@ -39,6 +39,55 @@ weapp-vite ide logs --open
 weapp-vite build
 ```
 
+### 构建并上传
+
+```bash
+wv build --upload --dry-run
+wv build --upload -p weapp
+
+# 独立命令保留六端批量上传能力
+wv upload --platform jd,swan
+wv upload --platform all --dry-run
+
+# 内置自动版本演练：不修改版本或锁文件
+wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
+```
+
+`build --upload` 复用本次构建，构建成功并校验产物后才上传，不重复构建。六个平台为 `weapp/alipay/tt/xhs/jd/swan`；独立 `wv upload` 还支持逗号分隔或显式 `all`，每个目标先构建再上传，失败后停止后续目标。上传不自动提审或正式上线；`--dry-run` 只构建和检查产物，不校验凭据、不调用 SDK。
+
+通常无需添加 `weapp.upload`：默认读取业务 `package.json.version`，说明自动生成为 `项目名@版本`；默认不升版、不读取 Git、不运行 npm。需要覆盖时传 `--uv` / `--desc` 或配置 `weapp.upload`；本地自动版本显式使用 CLI `--bump patch|minor|major` / `--git-desc`，二者分别与 `--uv` / `--desc` 冲突，不是 Vite 配置字段。真实升版需要本机 npm，只有 Git 说明要求已有提交的 Git 仓库。完整 `.env.test` / `.env.production`、独立 AppID、本地自动升版与 CI 配置见[上传环境与自动版本](https://vite.weapp.dev/guide/upload/environments.html)。普通 `build`、`dev/HMR` 不上传；配置仍正常求值。`build` 的上传专属参数必须与 `--upload` 一起使用，不能用于 watch 或 Web-only。
+
+自动元数据在首次配置求值、编译前准备一次，批量共用；升版仅处理命令根目录的应用清单，不向父目录查找、不执行生命周期钩子、不 commit/tag/push。dry-run 不运行 npm、不修改版本或锁文件，直接导入 `package.json` 的构建代码仍读取原始版本。实际升版后的构建或上传失败不回滚，重试去掉 `--bump` 并复用原版本。完整边界见[本地速查](./upload.md#内置本地自动版本)。
+
+`build -p all --upload` 是“小程序 + Web”，等两者都构建成功后只上传小程序，不等于独立 `upload -p all` 的六端批量上传。
+
+多个平台推荐使用一份 `weapp.multiPlatform.projectConfigs` 映射，公共字段用对象展开，各平台只提供 AppID 和差异；标准项目 JSON 由构建器生成，不必手工维护六份文件。原生文件方式仍可使用，完整示例见本地[上传速查](./upload.md#多平台与输出校验)。
+
+按目标安装官方工具，并通过未提交的 `.env.<mode>.local` 或 CI Secrets 提供凭据，不要在 `weapp.upload` 中添加凭据字段。先读本地 [六端上传与预览速查](./upload.md)，再按[分平台操作指南](https://vite.weapp.dev/guide/upload.html)配置 AppID、密钥或 Token。淘宝不在支持列表内；百度官方 CLI Token 会进入子进程参数，仅在可信隔离 runner 上运行。
+
+旧的微信 IDE 顶层上传仍可原样执行，不额外触发 weapp-vite 构建：
+
+```bash
+wv upload --project ./dist --version 1.2.3 --desc "release"
+wv upload -p ./dist -v 1.2.3 -d "release"
+```
+
+SDK 命令 `wv upload -p weapp` 无需 `--project`，会自动定位本次构建产物。这里的 `./dist` 只是假设旧 IDE 工程根位于该目录，不是默认值，应按实际 `project.config.json` 所在目录填写；旧入口省略定位参数时保持透传，不自动补 `dist`。
+
+旧顶层语法每次只警告一次未来弃用，不要求立即迁移；稳定的显式 `wv ide upload -p ./dist -v 1.2.3 -d "release"` 不弃用、不警告，仍依赖 IDE 登录。若改用 SDK，需要从源码项目根安装 `miniprogram-ci`、配置 AppID、上传私钥和 IP 白名单，再执行 `wv build --upload -p weapp --uv 1.2.3 --desc "release"`；不复用 IDE 登录，也不能把旧 `--project` 的产物目录直接作为 SDK `[root]`。
+
+`-p` 只有与明确旧标记（如 `--version/-v` 或 `--project`）一起出现时才是 IDE 项目目录，否则是平台，不猜测路径。新旧方言混用在 IDE、构建或升版副作用前报错，`--dry-run` / `--bump` / `--git-desc` 不能用于旧 IDE 上传。`wv upload --help` 是 SDK 帮助，`wv help upload` 保留旧 IDE 帮助并警告，`wv ide help upload` 不警告。完整标记、短参数和 `=` / `--` 规则见[本地速查](./upload.md#旧上传兼容与迁移)。
+
+### 构建并预览
+
+```bash
+wv preview -p tt --mode test
+wv preview -p xhs,jd,swan --mode production
+wv preview -p all --dry-run
+```
+
+使用同一套六端工具与凭据，先构建再调用官方预览接口，不上传开发版本、不提审、不正式发布。微信返回本次生成的本地二维码图片；支付宝、京东返回二维码图片 URL；抖音、小红书、百度返回预览链接。百度仍需 `SWAN_MIN_VERSION`；预览不使用上传默认参数，不接受 `--uv`、`--bump` 或 `--git-desc`。旧微信 IDE 预览使用 `wv ide preview --project <IDE项目根>`，不额外构建。
+
 ### 4. 分包预下载审计
 
 微信小程序可以检查静态跨分包跳转，并把建议输出为 JSON：
@@ -90,7 +139,7 @@ weapp-vite build
 wv dev -p web --host
 wv build -p web
 weapp-vite open
-weapp-vite preview --project ./dist/build/mp-weixin
+weapp-vite preview -p weapp --mode test
 weapp-vite ide preview --project ./dist/build/mp-weixin
 weapp-vite ide logs --open
 weapp-vite screenshot --project ./dist/build/mp-weixin --page pages/index/index --output .tmp/acceptance.png --json

package/dist/docs/index.md

@@ -16,7 +16,8 @@
 8. 涉及 wevu 运行时与页面/组件/store 约束时读 `wevu-authoring.md`。
 9. 涉及 Vue SFC 宏、模板约束与编辑器提示时读 `vue-sfc.md`、`volar.md` 与 `define-config-overloads.md`。
 10. 编写页面或组件单测时读 `testing.md`。
-11. 遇到告警、prepare、截图、日志、依赖异常时读 `troubleshooting.md`。
+11. 上传或预览小程序时读 `upload.md`，核对平台、AppID、凭据与输出目录。
+12. 遇到告警、prepare、截图、日志、依赖异常时读 `troubleshooting.md`。
 
 ## Included Docs
 
@@ -25,6 +26,7 @@
 - `volar.md`: Volar、JSON 宏与编辑器智能提示支持说明。
 - `define-config-overloads.md`: defineConfig 类型重载与配置推导说明。
 - `getting-started.md`: CLI 命令、prepare、build、screenshot、MCP 等快速入口。
+- `upload.md`: 六端上传/预览、AppID 与凭据、批量执行、CI 和淘宝支持边界。
 - `ai-workflows.md`: AI 代理在其他仓库里使用 weapp-vite 的推荐工作流。
 - `project-structure.md`: AGENTS.md、.weapp-vite、dist 与源码目录的职责说明。
 - `weapp-config.md`: weapp 配置、autoRoutes、autoImportComponents、routeRules 与 chunk 策略。

package/dist/docs/upload.md

@@ -0,0 +1,189 @@
+# 小程序上传与预览速查
+
+此文档随当前 `weapp-vite` 版本发布。面向已有可构建的小程序项目；完整分步教程见[上传与预览指南](https://vite.weapp.dev/guide/upload.html)。上传只产生开发版本，不自动提审或正式上线。
+
+`test` / `production`、不同 AppID 与自动版本/提交说明见[多环境上传](https://vite.weapp.dev/guide/upload/environments.html)。
+
+下文的构建、环境凭据、dry-run 与自动版本规则只适用于 SDK 入口；原有微信 IDE 顶层上传保留原参数行为，见[旧上传兼容与迁移](#旧上传兼容与迁移)。
+
+## 选择平台与凭据
+
+先在业务项目安装目标平台的工具，例如 `pnpm add -D xhs-mp-cli`。不要只全局安装，也不需要为单个平台安装六套工具。
+
+| 平台            | SDK 包              | 源码项目配置 / 代码根字段                 | 必需凭据和其他元数据                                                                      |
+| --------------- | ------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------- |
+| 微信 `weapp`    | `miniprogram-ci`    | `project.config.json` / `miniprogramRoot` | `WEAPP_CI_PRIVATE_KEY_PATH`：代码上传私钥文件，不是 AppSecret                             |
+| 小红书 `xhs`    | `xhs-mp-cli`        | `project.config.json` / `miniprogramRoot` | `XHS_UPLOAD_TOKEN`：官方代码上传秘钥内容                                                  |
+| 抖音 `tt`       | `tt-ide-cli`        | `project.config.json` / `miniprogramRoot` | `TT_UPLOAD_TOKEN`：官方 CLI Token                                                         |
+| 支付宝 `alipay` | `minidev`           | `mini.project.json` / `miniprogramRoot`   | `ALIPAY_IDENTITY_KEY_PATH`：含 `alipay.authentication` 的官方 JSON 身份密钥文件，不是 PEM |
+| 京东 `jd`       | `jd-miniprogram-ci` | `project.config.json` / `miniprogramRoot` | `JD_PRIVATE_KEY`：完整密钥内容，不是文件路径                                              |
+| 百度 `swan`     | `swan-toolkit`      | `project.swan.json` / `smartProgramRoot`  | `SWAN_UPLOAD_TOKEN`：BDUSS；`SWAN_MIN_VERSION`：最低基础库版本，不是应用版本              |
+
+**淘宝不支持**：当前没有 `taobao` 平台或上传适配器，`alipay` 固定使用支付宝客户端，不能冒充淘宝。Web、组件库、独立插件也不在此入口范围内。
+
+AppID 写入源码侧项目配置的 `appid`。微信可用 `WEAPP_CI_APPID`、支付宝可用 `ALIPAY_APP_ID` 覆盖上传使用的 ID，但必须与密钥授权一致；抖音 `TT_APP_ID`、小红书 `XHS_APP_ID` 如设置，必须与生成项目配置的 `appid` 相同，不能用来切换应用。抖音、小红书、百度不能只填写 `appId`；京东和百度没有 AppID 环境覆盖项。
+
+## 单平台完整配置与命令
+
+以小红书为例，已有项目保留其他构建配置。`vite.config.ts`：
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+export default defineConfig({
+  weapp: {
+    platform: 'xhs',
+    srcRoot: 'src',
+  },
+})
+```
+
+源码根 `project.config.json` 的最小上传相关字段（占位值必须替换；已有配置保留其他字段）：
+
+```json
+{
+  "appid": "replace-with-xhs-app-id",
+  "compileType": "miniprogram",
+  "miniprogramRoot": "dist"
+}
+```
+
+源码根 `.env.production.local`：
+
+```dotenv
+XHS_UPLOAD_TOKEN=replace-with-official-code-upload-secret
+```
+
+```bash
+pnpm add -D xhs-mp-cli
+pnpm exec wv build --upload -p xhs --dry-run
+pnpm exec wv build --upload -p xhs
+pnpm exec wv preview -p xhs --desc "验收首页"
+```
+
+无需配置 `weapp.upload`：版本默认读取业务 `package.json.version`，说明按包名与最终版本自动生成 `name@version`；默认不升版、不读取 Git、不运行 npm。仅需固定覆盖时才设置 `weapp.upload.version` / `desc`；一次性覆盖可用 CLI：
+
+```bash
+pnpm exec wv build --upload -p xhs --uv 1.2.4 --desc "修复首页展示"
+```
+
+版本优先级为 CLI `--uv` 或 `--bump` 生成值 > `weapp.upload.version` > `package.json.version`；说明为 CLI `--desc` 或 `--git-desc` 生成值 > `weapp.upload.desc` > 自动生成值。去除首尾空白；显式空版本报错，空说明用自动生成值。普通 `build`、`dev/HMR` 不启用上传，配置文件本身仍正常求值。`preview` 不使用 `weapp.upload` 默认参数，不需要版本，也不接受 `--uv`、`--bump` 或 `--git-desc`。
+
+`build --upload` 只编译一次，等本次所有后端构建成功、产物校验通过才上传。SDK `wv upload` 也会自行构建，不需要先执行 `build`。普通 build 不能单独带 `--uv` / `--desc` / `--bump` / `--git-desc` / `--dry-run`；上传不能与 `--watch` 或 Web-only 组合。
+
+## 内置本地自动版本
+
+不需要辅助脚本或额外依赖；沿用已配置的应用与平台，从应用根目录执行：
+
+```sh
+# 计算下一版本和说明，构建但不修改版本文件、不上传
+pnpm exec wv upload -p xhs,tt --mode test --bump patch --git-desc --dry-run
+
+# 确认后选择批量或单目标入口，不要重复执行两条真实上传命令
+pnpm exec wv upload -p xhs,tt --mode test --bump patch --git-desc
+pnpm exec wv build --upload -p xhs --mode test --bump patch --git-desc
+```
+
+- `--bump <release>` 只接受 `patch`、`minor`、`major`，要求应用有合法的 SemVer 版本；与显式 `--uv` 冲突。
+- `--git-desc` 读取最新 Git 提交的 subject，不读取正文；与显式 `--desc` 冲突。生成的版本和说明覆盖 `weapp.upload` 默认值。
+- 两个选项可独立启用，只用于 `upload` / `build --upload`，不能放进 Vite 上传配置。真实升版需要本机 npm；只有 `--git-desc` 要求 Git 可执行且仓库已有提交。
+- 只处理命令 `[root]` 直接包含的 `package.json`；省略 root 即当前目录，不向父目录查找，Vite `root` / `envDir` 不改变目标。首次编译器初始化、配置求值前只准备一次，整批共用版本与说明。
+- 真实升版由 npm 标准 `version` 操作更新应用版本与适用的 npm 锁文件，不同步 `pnpm-lock.yaml`。`--prefix`、工作目录均限定为应用根，传入 `--no-git-tag-version --ignore-scripts --workspaces=false`，不修改外层 workspace 根包，不运行生命周期钩子、不 commit/tag/push。
+- dry-run 不运行 `npm version`，不修改版本或锁文件；直接导入 `package.json` 的构建代码仍读取原始版本，而不是预计上传版本。演练不要求 npm，启用 `--git-desc` 时仍要求 Git。
+- 参数冲突、无效 release / 当前版本、Git 失败都在文件修改前报错。升版完成后构建或上传失败不回滚；只重试未完成的平台，去掉 `--bump`，必要时用 `--uv` / `--desc` 显式复用上一批版本与说明。
+
+CI 可继续按 `run_number` 生成版本并显式传 `--uv` / `--desc`，不需要改写应用版本文件。完整工作流见[多环境上传](https://vite.weapp.dev/guide/upload/environments.html#ci)。
+
+## 环境与密钥安全
+
+- 默认 mode 为 `production`；`--mode test` 选择测试环境文件，但仍是生产构建。
+- 覆盖优先级：`.env` → `.env.local` → `.env.<mode>` → `.env.<mode>.local` → 进程环境。不要用保留的 mode `local`。
+- 环境目录由 Vite `root` / `envDir` 决定；`envDir: false` 只读取进程环境。
+- 两个密钥文件路径相对源码项目根（命令的 `[root]`），不是相对环境目录或输出目录。
+- `.env.local`、`.env.*.local`、`.keys/` 加入 `.gitignore`；密钥放在源码和静态资源目录之外，不加 `VITE_` 前缀。
+- CI 使用 Secrets 或临时安全文件，测试通过后显式上传；文件用后删除，不向不可信 PR 暴露凭据。
+
+## 多平台与输出校验
+
+单平台根目录原生 JSON、多平台各端独立 JSON、统一 `projectConfigs` 三种入口都保留，不强制迁移。想减少重复文件时，可以在一份 `vite.config.ts` 中使用 `weapp.multiPlatform.projectConfigs`：
+
+```ts
+import { defineConfig } from 'weapp-vite/config'
+
+const common = { projectname: 'my-app' }
+
+export default defineConfig({
+  weapp: {
+    srcRoot: 'src',
+    multiPlatform: {
+      projectConfigs: {
+        xhs: { ...common, appid: 'replace-with-xhs-app-id' },
+        tt: { ...common, appid: 'replace-with-douyin-app-id' },
+      },
+    },
+  },
+})
+```
+
+省略 `targets` 时从平台键推导允许列表；公共字段用普通对象展开，平台字段覆盖公共字段，不做隐式深合并。标准项目 JSON 由打包器生成在代码目录内，默认 `dist/<平台>/dist/`，SDK 代码根为 `.`。不要在输入对象中写 `miniprogramRoot`、`srcMiniprogramRoot`、`smartProgramRoot`，自定义目录使用 `build.outDir`。不读原生或私有项目 JSON；缺少选中平台直接报错，不回退到旧文件。
+
+平台字段和嵌套设置提供智能提示，同时保留未知原生扩展字段及新增字符串取值，不需要 `as any`。独立映射可从 `weapp-vite/config` 导入 `MultiPlatformProjectConfigs`，使用 `satisfies MultiPlatformProjectConfigs` 保留补全和扩展字段推导。已知字段类型、六端平台键和生成代码根限制仍生效；未知字段是否可用由原生工具决定。
+
+`defineConfig` 保持通用泛型推导，不做精确对象校验；混合正确与错误平台键时，TypeScript 可能不报错。需要静态检查平台名拼写时用上述 `satisfies`，构建时仍拒绝不支持的平台。
+
+原生文件模式仍支持各端独立维护：默认 `projectConfigRoot: 'config'` 从 `config/<平台>/` 读取 JSON；若使用 `weapp/project.config.json`、`alipay/mini.project.json`、`tt/project.config.json`、`xhs/project.config.json`、`jd/project.config.json`、`swan/project.swan.json` 这些项目根下的平台目录，设为 `projectConfigRoot: '.'` 即可。只维护部分平台时显式选择这些平台，不需要补齐其余文件。
+
+原生代码根为 `dist` 时，配置复制至 `dist/<平台>/`，代码在 `dist/<平台>/dist/`。两种多平台来源不能同时配置。多平台仍显式传 `-p`，不能使用 `--project-config`；单平台不启用 multiPlatform 时仍读取根目录原生 JSON，也可指定该参数，但文件名必须是目标平台的标准名称。Token/私钥始终留在环境变量，不写入项目配置。
+
+```bash
+pnpm exec wv upload -p xhs,tt
+pnpm exec wv upload -p all --dry-run
+pnpm exec wv preview -p xhs,tt
+```
+
+`upload/preview -p all` 是六端：微信、支付宝、抖音、小红书、京东、百度；`build -p all --upload` 则是“小程序 + Web”，不是六端。`build` 不接受多个小程序平台的逗号列表。批量串行、首次失败停止，成功的前序平台不会自动撤回；仅配置部分平台时显式列出它们，`all` 不会按 `multiPlatform.targets` 自动缩减。
+
+每次校验 SDK 代码根与本次输出实际路径相同且含 `app.json`。百度检查 `smartProgramRoot`，其他平台检查 `miniprogramRoot`；不要用 `srcMiniprogramRoot` 替代，也不要通过修改旧 `dist` 绕过校验。
+
+## 平台限制与预览结果
+
+- 微信：上传私钥对应 AppID，配置平台 IP 白名单；可选 `WEAPP_CI_ROBOT` 为 1–30。预览图片输出到 `.weapp-vite/preview/`。
+- 支付宝：上传版本为三段数字、无前导零、每段不超过 2147483647；说明少于 200 字符。预览返回二维码图片 URL。
+- 抖音：上传版本为三段数字。SDK 会在本地保存 Token，使用隔离 runner。预览返回扫码链接。
+- 小红书：只走 Token 认证，不回退扫码登录。预览返回扫码链接。
+- 京东：上传与预览共用官方 SDK 临时包，同机共享临时目录的任务必须串行；预览返回二维码图片 URL。
+- 百度：上传版本为二至四段数字；预览也必填 `SWAN_MIN_VERSION`，只支持普通小程序。BDUSS 出现在 SDK 子进程参数中，使用可信隔离 runner；预览返回默认基础库的扫码链接。
+
+`--dry-run` 不加载 SDK、不校验凭据或官方平台规则、不生成二维码；上传入口仍要求非空版本。它不能证明平台授权、网络、IP 白名单或扫码权限正确。上传失败后保留错误并定位根因，不把 SDK 提前退出视为成功；取消命令不能撤回已被平台接收的版本。
+
+## 完整教程
+
+- [微信](https://vite.weapp.dev/guide/upload/weapp.html)
+- [小红书](https://vite.weapp.dev/guide/upload/xhs.html)
+- [抖音](https://vite.weapp.dev/guide/upload/tt.html)
+- [支付宝及淘宝边界](https://vite.weapp.dev/guide/upload/alipay.html)
+- [京东](https://vite.weapp.dev/guide/upload/jd.html)
+- [百度](https://vite.weapp.dev/guide/upload/swan.html)
+- [批量操作](https://vite.weapp.dev/guide/upload.html#batch)、[CI 示例](https://vite.weapp.dev/guide/upload.html#ci)、[排障](https://vite.weapp.dev/guide/upload.html#troubleshooting)
+
+## 旧上传兼容与迁移
+
+原有微信 IDE 上传的长、短参数保持不变，无需立即改写脚本：
+
+```bash
+wv upload --project ./dist --version 1.2.3 --desc "release"
+wv upload -p ./dist -v 1.2.3 -d "release"
+wv upload --project=./dist --version=1.2.3 --desc="release"
+```
+
+旧入口保留版本、说明和项目定位的原始语义。上述 `./dist` 仅是 IDE 工程路径示例，应替换为包含 `project.config.json` 的实际工程根；省略 `--project/-p` 或 `--appid` 时仍保持透传，不会自动补 `dist`，由官方 CLI 处理。顶层旧语法每次调用只警告一次，提示未来将移除；稳定的 `wv ide upload -p ./dist -v 1.2.3 -d "release"` 不弃用、不警告。两者沿用 IDE 登录和已有项目，不额外运行 weapp-vite 构建。
+
+普通 SDK 上传直接执行 `wv upload -p weapp`，无需 `--project`：框架自动依据项目配置与本轮实际写出目录定位产物。多平台默认代码目录是 `dist/<平台>/dist/`，也支持自定义输出；不是固定上传 `./dist`。
+
+SDK 迁移不是等价换名：回到包含 `package.json`、Vite 配置和源码的项目根，安装 `miniprogram-ci` 并配置 AppID、上传私钥和 IP 白名单，再执行 `wv build --upload -p weapp --uv 1.2.3 --desc "release"`。不要把旧 `--project` 的构建产物目录当作 SDK `[root]`；SDK 需要新凭据，不复用 IDE 登录。
+
+- 旧标记为 `--version/-v`、`--project`、`--appid`、`--ext-appid`、`--info-output/-i`；SDK 标记为长参数 `--platform`、`--uv`、`--bump`、`--git-desc`、`--dry-run`。混用在 IDE、编译或版本修改前报错；SDK 标记的 `--no-*` 形式也不能混入旧调用。dry-run、自动升版与 Git 说明不适用于 IDE。
+- `-p` 仅在有旧标记时表示 IDE 项目目录，否则表示原生平台；不根据路径存在与否或值是否像平台名猜测。`--desc` 共用，`-d` 仅在旧调用中是说明，原生命令中仍是 debug。
+- 参数支持分开和 `=` 形式；必填值只是数据，仅在选项位置遇到 `--` 后停止扫描。
+- `wv upload --help` 查看 SDK 帮助；`wv help upload` 保留旧 IDE 帮助并警告未来弃用；`wv ide help upload` 保持显式 IDE 帮助、不警告。工具自身版本查询用 `wv --version`。
+- 兼容只覆盖顶层旧上传，不包含顶层预览。`wv preview` 仍走 SDK；IDE 预览继续用 `wv ide preview --project ./dist`。