weapp-vite 7.3.0 → 7.5.0

package/dist/docs/upload.md

@@ -0,0 +1,226 @@
+# 小程序上传与预览速查
+
+此文档随当前 `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`。
+- 环境文件采用 `dotenv-expand 1000.0.0`：文件值中的 `$(...)` 自动执行命令替换；提供 `DOTENV_PRIVATE_KEY` 时，`encrypted:` 前缀的文件值会尝试解密，未提供私钥时保留该值。没有公开的命令替换或解密禁用开关，反斜杠不能阻止 `$(...)` 命令替换，只加载可信文件。
+- 进程同名值包括空字符串均原样采用；被覆盖的文件值在展开前排除，不执行其命令替换或解密。加载器不将展开后的凭据写回 `process.env`。
+- 含字面 `$(...)` 的凭据直接通过 CI Secrets 或进程环境提供，不写入环境文件，也不在其他文件变量中再次引用它；引用展开后仍可能执行命令替换。
+- 环境目录由 Vite `root` / `envDir` 决定；`envDir: false` 完全禁用此入口的环境文件加载与展开，只读取进程环境，不对其值执行命令替换或解密。
+- 两个密钥文件路径相对源码项目根（命令的 `[root]`），不是相对环境目录或输出目录。
+- `.env.local`、`.env.*.local`、`.keys/` 加入 `.gitignore`；密钥放在源码和静态资源目录之外，不加 `VITE_` 前缀。
+- CI 使用 Secrets 或临时安全文件，测试通过后显式上传；文件用后删除，不向不可信 PR 暴露凭据。
+
+单层反向引用 `A=$B`、`B=value` 仍可展开；多级反向声明 `A=$B`、`B=$C`、`C=value` 会得到 `A` 为字面 `$C`，而 `B`、`C` 为 `value`。多级引用应按依赖顺序先定义基础值，例如依次声明 `C=value`、`B=$C`、`A=$B`，不要依赖任意反向链递归展开。
+
+变量引用必须无环，否则展开可能停滞。避免在同一文件重复声明同名变量；覆盖放到更高优先级的环境文件，先声明基础值，再声明引用它的变量。合并后的文件变量按最后生效声明的位置展开，以复用已经展开的命令输出或解密结果。
+
+默认值与替代值表达式区分未定义和空字符串：
+
+| 表达式 | `VAR` 未定义 | `VAR` 是空字符串 |
+| --- | --- | --- |
+| `${VAR-fallback}` | `fallback` | 空字符串 |
+| `${VAR:-fallback}` | `fallback` | `fallback` |
+| `${VAR+alternate}` | 空字符串 | `alternate` |
+| `${VAR:+alternate}` | 空字符串 | 空字符串 |
+
+## 多平台与输出校验
+
+单平台根目录原生 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 提前退出视为成功；取消命令不能撤回已被平台接收的版本。
+
+## 结构化结果与本地超时
+
+```bash
+wv upload -p xhs,tt --json --timeout 180 > upload-report.json
+wv upload -p all --dry-run --json
+```
+
+`--json` 让 stdout 只输出一个报告，日志和官方进度进入 stderr；失败退出码非零。不使用 JSON 时仍打印逐平台汇总。`--json` / `--timeout` 仅适用于独立 SDK `upload`，不适用于 `build --upload`、`preview`、IDE 上传或 `weapp.upload` 配置。
+
+报告为 `{ schemaVersion: 1, action: "upload", status, results, error? }`。整批 `status` 为 `success` / `failed`；`results` 按请求顺序保留各平台的 `platform`、可选 `requestedVersion`、最后进入的 `stage`（`prepare` / `build` / `validate` / `upload`）及 `status`（`success` / `failed` / `not-run` / `dry-run` / `unknown`）。从配置推断但尚未解析的平台为 `null`；列表解析前失败时 `results` 可为空。首次失败后保留前序结果，后续条目为 `not-run`。
+
+成功条目的 `result` 只含官方实际返回的可选信息：微信的 `subPackages` / `plugins`（体积为字节），支付宝的 `sdkVersion` / `qrCodeUrl`，抖音的 `previewUrl` / `qrCodeFile`，京东的 `qrCodeUrl` / `qrCodeBase64`，百度的 `previewUrl` / `fileSize` / `warnings`；小红书成功结果为 `{}`。不从请求版本或内部标识推断 SDK 确认版本，不因可选信息缺失而改判失败。字段结构见[完整结果参考](https://vite.weapp.dev/guide/upload.html#report)。
+
+进度只使用公开能力：微信任务状态／消息、小红书百分比、支付宝日志／任务创建／版本创建事件。其他平台不伪造百分比；任何进度事件都不能替代 SDK 完成确认和正常退出。
+
+`--timeout` 是每个平台 SDK worker 的本地超时，不含构建；默认不增加超时。值为正数秒，精度不超过毫秒，最大 `2147483.647` 秒。SDK 执行期间，`SIGINT` / `SIGTERM` 或超时会触发本地上传进程树清理，无法确认清理完成时报告错误。构建等前置阶段保留原有信号退出行为，不等待挂起的构建，也不保证生成最终报告。
+
+Windows 使用 PowerShell 查询已退出 worker 的子进程归属，单次查询最多等待 30 秒；这是 SDK 执行结束后的本地清理预算，不包含在 `--timeout` 内。查询或终止失败仍然报错，不会跳过清理或自动重试上传。
+
+SDK 开始后超时／中断标记 `status: "unknown"`、`remoteOutcome: "unknown"`；SDK 尚未开始时可为 `remoteOutcome: "not-started"`。其他 SDK 错误也可能携带 `remoteOutcome: "unknown"`。**本地停止不代表远端取消**，先核实平台状态再重试；不会自动重试、回滚、提审、设置体验版或正式发布。
+
+## 完整教程
+
+- [微信](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`、`--json`、`--timeout`。混用在 IDE、编译或版本修改前报错；SDK 标记的 `--no-*` 形式也不能混入旧调用。SDK 专属选项不适用于 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`。

package/dist/docs/vite-plugin.md

@@ -0,0 +1,171 @@
+# 标准 Vite 插件与 Vite+
+
+`weapp-vite/vite` 提供实验性的生产构建、classic 与 stateful 开发入口。当前阶段支持六平台单目标原生 JS/TS、Wevu Vue SFC 编译；微信另已验收 React、自动路由、自动组件、普通分包、独立分包、worker、微信插件双产物与 lib mode。主产物由宿主 Vite 的编译管线生成。
+
+## 配置
+
+项目使用 ESM（`package.json` 设置 `"type": "module"`），或将配置命名为 `vite.config.mts`：
+
+```ts
+import { defineConfig } from 'vite'
+import { weapp } from 'weapp-vite/vite'
+
+export default defineConfig({
+  plugins: [weapp()],
+  weapp: {
+    platform: 'weapp',
+    srcRoot: 'src',
+    hmr: { runtime: 'classic' },
+  },
+})
+```
+
+插件没有第二套配置参数。配置文件由宿主加载，插件不会自动发现或合并另一份 `weapp-vite.config.*`。迁移时把配置收敛到一个入口；需要拆文件时，在该入口显式导入。不要重复调用 `weapp()`，也不要把同一插件实例共享给两个活动宿主。
+
+```sh
+vite build
+vite dev
+```
+
+`mode: 'test'` 仍可用于生产构建。测试识别依赖实际 Vitest 宿主标识，不根据 mode 猜测。只读取配置不会扫描小程序入口、生成支持文件或启动 IDE/MCP；`wv prepare` 继续负责类型支持文件。
+
+## Vite+
+
+配置中的 `defineConfig` 改为从 `vite-plus` 导入，然后使用 `vp build` / `vp dev`。Vite+ 消费项目须按官方迁移规则把 `vite` 指向配套 core，并确保 weapp-vite 的依赖也解析到同一宿主。例如 npm 项目：
+
+```json
+{
+  "type": "module",
+  "devDependencies": {
+    "vite-plus": "1.0.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0"
+  }
+}
+```
+
+pnpm 使用项目级 `pnpm-workspace.yaml` 的 `overrides` 完成同样的 alias；不要只修改顶层依赖而留下 weapp-vite 内嵌的另一套 Vite。该组合对应 Vite 8.3.1 / Rolldown 1.2.11；Vite+ 项目验证线为 Node 24.11+，普通 weapp-vite 的 Node 范围不变。
+
+## 当前命令边界
+
+| 命令 | 当前行为 |
+| --- | --- |
+| `vite build` / `vp build` | 实验性单目标小程序生产构建 |
+| `wv dev` / `wv build` | 保留原有能力；显式插件不会重复安装编译器 |
+| `vite dev` / `vp dev` | 实验性 classic / stateful 开发；由宿主管理启动、重启与关闭 |
+| `vite build --watch` / `vp build --watch` | 实验性生产 watch：完整目标产物、入口增删与失败恢复 |
+| `vp test` | 插件不启动小程序编译；mpcore 测试继续显式使用 artifact API |
+| `wv prepare/open/upload/mcp` | 继续使用小程序专属命令 |
+| `vp preview` | Vite 的 Web 预览，不是小程序二维码预览 |
+| `vp pack` | 通用库打包，不替代小程序 lib mode |
+
+每次调用选择一个目标。纯 Web 使用 `weapp.platform: 'web'`；Web/小程序同宿主混合开发仍未开放。
+
+生产构建、build watch、classic 与实验性 stateful dev 已接入。脚手架支持与业务模板独立的 `--toolchain=wv|vite|vite-plus`，生成对应宿主脚本、显式配置入口和 Vite+ core alias；小程序专属命令继续使用 `wv`。任务缓存、Dashboard/MCP 会话复用和完整跨平台发布矩阵仍属于后续阶段。完整编译能力对齐继续由 #1097 追踪；高级目标限制是阶段边界。
+
+## classic 开发
+
+`vite dev` / `vp dev` 由宿主负责服务器和配置重载，小程序会话复用现有增量编译调度，产物经 Vite/Rolldown 原生 write 落盘。首次完整产物就绪后才打印小程序就绪日志。脚本、模板、样式和页面增删会更新产物；语法错误修正后继续编译。宿主 `server.close()`（包括 middleware mode）会等待正在执行的构建再释放自有资源。
+
+classic 模式不支持宿主 `experimental.bundledDev: true`，开启时会在启动前报错。classic 更新遵循完整重载语义，不承诺实例状态保持。`wv dev` 保留原有 HMR 选择和全部目标能力。
+
+同一宿主目前只编译一个小程序目标，暂不支持同时开发 Web。插件不会自动打开 IDE、启动 MCP 或上传。
+
+## 检查与排障
+
+- 缺少入口：核对 `weapp.srcRoot`、`app.json`/`app.vue` 和宿主的 `root`。
+- ESM 配置加载失败：使用 `type: module` 或 `.mts`，不依赖旧 CLI 的 runner 回退。
+- 引擎加载失败：核对 Vite+ core alias 和实际解析路径；配套引擎缺失时会报错，不静默切换到其他 Rolldown。
+- 类型检查：继续使用 `wv prepare`、`vue-tsc`/`tsc`、ESLint 与 stylelint；`vp check` 不能替代全部小程序规则。
+- 缓存：开发服务、IDE、上传、MCP 与 runtime E2E 不应配置任务缓存。生产缓存的完整恢复与输入失效矩阵尚未验收。
+
+跟踪：[标准插件与 Vite+ 集成 #1097](https://github.com/weapp-vite/weapp-vite/issues/1097)。
+
+## 生产 watch
+
+`vite build --watch` 与 `vp build --watch` 复用生产配置，每轮通过宿主 emit/write 发布当前目标的完整产物。支持脚本、模板、样式更新，页面增删和语法错误恢复；删除页面时清理对应的已拥有产物及 sourcemap。`emptyOutDir: false` 时保留其他工具写入的文件。关闭 watcher 会等待本轮写出和会话资源释放。
+
+这一路径不提供状态保持 HMR，也不自动重启配置文件。修改 Vite 配置或配置依赖后，按宿主 build watch 的语义重新启动命令；需要配置自动重启时使用 classic `vite dev` / `vp dev`。目标能力限制与插件生产构建一致。
+
+## 实验性 stateful 开发
+
+在同一顶层配置中设置 `weapp.hmr.runtime: 'stateful-experimental'`，继续使用 `vite dev` / `vp dev`。适配器安装在宿主的 client 环境，使用其配套 Rolldown DevEngine；不会另起一个 Vite 服务。无需手工开启 `experimental.bundledDev`，但宿主必须提供所需私有 API，能力检查失败会明确报错。
+
+该模式面向微信 WebView，需开启微信开发者工具热重载。当前宿主遇到 Skyline 或缺失私有 API 时明确报错，需显式改用 classic；独立 CLI 的自动降级行为保留。JS 安全补丁、模板与样式更新复用现有 stateful 协议；页面入口拓扑变化由宿主重新创建会话，配置依赖变化由宿主重新加载配置。关闭会等待本会话拥有的任务和引擎；不会关闭其他宿主实例。
+
+普通 Vite 与 Vite+ 均已验证原生 Page/Component 脚本补丁、样式更新、模板往返及 Wevu 本地/store 状态保持，包含 headless 可观察语义与真实微信 IDE。Vite+ 验收在严格安装的独立发布包依赖图中使用原生 `vp dev`；独立 `wv` 同时通过同组 headless 与真实微信 IDE 回归。当前结果覆盖这些定向场景，完整跨平台发布矩阵仍需持续验证。
+
+middleware mode 支持构建与可等待关闭。运行小程序的 stateful 通信还需要消费方把 Vite middleware 挂载到可访问的 HTTP 服务，并配置对应端口；只创建 middleware 服务不会自动提供监听端点。
+
+## React
+
+注册同一个 `weapp()`，继续使用顶层 `weapp.react` 配置和既有 `@weapp-vite/react` 运行时。生产构建、classic、生产 watch 与实验性 stateful 共用 React 编译器；静态 TSX 在 stateful 下按既有规则重建会话，不承诺 React hooks 状态跨此类重载保持。
+
+`renderMode: 'auto'` 可组合静态 WXML、动态模板与原生/Wevu 组件 bridge；`dynamic` 仍不支持原生组件 bridge。React Compiler 继续是可选 SWC 能力，其安装与降级规则不随宿主改变。模板输出使用共享的源码根与输出路径映射，支持自定义 `srcRoot` 和符号链接项目路径。
+
+## 独立分包
+
+`app.json` 或 `app.vue` 中的 `subPackages[].independent`，以及顶层 `weapp.subPackages` 的配置沿用独立 CLI 语义。三入口共享独立子构建；子构建直接复用本次已加载的配置、CLI 覆盖与用户插件，不再次执行配置文件。
+
+每个子构建只生成内存产物，最终由主构建的 Vite/Rolldown 发布。classic、stateful 和原生生产 watch 由宿主调度子包更新，不为独立分包另外创建 watcher。生产 watch 支持独立脚本与模板依赖、语法错误恢复，以及删除分包后的陈旧产物清理。
+
+stateful 下独立分包源码由宿主 watcher 驱动完整更新批次，不承诺子包 JS 状态保持；子包的 Vue、脚本和伴随资产无需进入主 DevEngine 模块图也能触发更新。
+
+## worker
+
+沿用 `app.json` 的 `workers` 与顶层 `weapp.worker.entry`，三入口使用同一子目标编译。原生 app builder 纳入 worker 环境，子目标复用已加载的配置和用户插件，返回内存产物；最终由主应用原生 emit/write 一次发布。
+
+classic、stateful 和生产 watch 不为 worker 额外启动构建 watcher。输入归属主会话，包含 worker 依赖修改、错误恢复、新增导入以及关闭等待；从 app 配置移除 worker 后，生产 watch 清理旧输出。stateful 中 worker 变化触发完整更新，不承诺保留 worker 线程状态。
+
+## 微信插件项目
+
+三入口共用顶层 `weapp.pluginRoot` 与 `project.config.json` 的插件输出配置。生产构建通过 app builder 登记 `weapp_plugin` 环境，在主应用落盘后构建插件，复用本次已加载配置与用户转换插件。主应用、插件和插件 npm 全部完成后才报告成功。
+
+插件输出可放在主应用输出内部或同级目录，但不能等于或包含主应用输出目录。classic 与 stateful 宿主都保留独立的插件编译会话，由父会话负责关闭；插件 watcher 负责增量更新与入口拓扑重建，不承诺插件 JS 状态保持。生产 watch 支持共享依赖、编译失败恢复和插件页面移除。
+
+当前阶段不支持双产物的 `build.write: false`，会提前报错。npm 自定义回调和手工映射共用上述输出归属规则；真实插件 runtime 仍需按目标平台验收。
+
+手工 npm 关联从主 `packageJsonPath` 所在目录解析依赖，再按 Node 规则向上查找；递归依赖从所属父包解析。CLI 缓存跟踪所选 manifest 的依赖变化，回调的工程 `root` 和相对输出基准保持不变。外部父子映射迁移时，按整轮绝对文件归属差集删除旧文件，不会误删当前产物或用户文件。
+
+## 小程序组件库
+
+顶层 `weapp.lib` 直接用于 `wv build`、`vite build` 和 `vp build`。原生组件、Vue SFC、纯脚本入口及 `fileName` 输出映射沿用同一编译器，声明文件与 JS、JSON、模板和样式一起进入原生 bundle；`build.write: false` 返回包含声明的内存产物。
+
+生产 watch 追踪声明编译器发现的类型依赖，类型变更会重新生成声明。每轮声明编译使用独立 TypeScript 缓存，避免旧类型跨轮复用。classic `dev` 可用于组件库源码更新，开发模式沿用独立 CLI 不生成声明的规则；组件交互在消费它的小程序应用中验证。
+
+`vp pack` 继续使用通用库打包语义；小程序库的模板、样式、JSON 和专属声明仍通过 `weapp.lib` 构建。
+
+
+## 六平台目标选择
+
+三入口共用顶层 `weapp.platform`，可选择 `weapp`、`alipay`、`tt`、`swan`、`jd`、`xhs`。启用 `weapp.multiPlatform` 时也可通过该字段指定本次目标，独立 CLI 继续接受 `--platform`。普通 Vite/Vite+ 命令不接受 `wv` 专属的 `--platform` 参数；多目标使用不同配置文件或任务，并确保输出目录独立。
+
+```ts
+import { defineConfig } from 'vite'
+import { weapp } from 'weapp-vite/vite'
+
+export default defineConfig({
+  plugins: [weapp()],
+  weapp: {
+    platform: 'alipay',
+    srcRoot: 'src',
+    multiPlatform: true,
+    hmr: { runtime: 'classic' },
+  },
+})
+```
+
+目录式平台项目配置从 `config/<platform>/` 读取，默认发布到 `dist/<platform>/`，小程序产物位于其 `dist/` 子目录。项目配置同样通过配套原生引擎写出，生产 watch 更新并清理本会话已拥有的文件；拒绝覆盖小程序编译输出的配置目录内容。目录式配置暂不支持 `build.write: false`，内联 `multiPlatform.projectConfigs` 可随主 bundle 返回内存产物。配置目录中的符号链接尚未开放。
+
+原生 TS 和 Vue SFC 的六平台生产构建、classic 更新，以及普通 Vite/Vite+ 的生产 watch 使用同一消费矩阵。stateful 仅开放微信；其他平台明确使用 classic。微信运行时使用 headless 与真实 IDE 验收；其他平台的构建/增量检查不代表各自真实 IDE runtime 均已通过，高级能力仍按平台分别验收。
+
+
+## 纯 Web 目标
+
+三入口都可在顶层设置 `weapp.platform: 'web'`，沿用 `weapp.web` 的源码根、输出目录和 runtime 配置；未指定 `weapp.web` 时使用 Web 默认值。普通 Vite 与 Vite+ 继续注册同一个 `weapp()`，独立 `wv` 无需注册插件，也无需再传 `--platform web`。显式 CLI `--platform` 覆盖配置目标。
+
+项目需保留既有 Web `index.html`，通过 `/@weapp-vite/web/entry` 启动 runtime。纯 Web 不要求小程序 `project.config.json`，默认输出 `dist/web`，不会同时生成小程序 bundle。原生生产构建、开发服务和插件生产 watch 使用宿主生命周期；Web 的浏览器 HMR 不启用微信 stateful 引擎。
+
+生产产物与 dev 服务均使用浏览器验证 Vue SFC、原生组件语义和交互。Web 测试只证明浏览器目标，不替代六个平台真实 IDE 验收。Web/小程序混合宿主仍会明确报错，后续需独立环境隔离后再开放。

package/dist/docs/vue-sfc.md

@@ -124,6 +124,18 @@ defineOptions({ behaviors: [i18n.behavior] })
 <view class="br" />
 ```
 
+## 原生插槽与 `provide` / `inject`
+
+`weapp.vue.template.scopedSlotsRequireProps` 默认 `false`，普通插槽仍使用增强方案。设为 `true` 时，无 scoped props 的内容保留原生 `<slot>`。
+
+微信目标下，编译后的 Wevu Provider 和 Leaf 使用默认 `setupLifecycle: 'attached'` 时，`<Provider><Leaf /></Provider>` 中的 Leaf 会在 setup 前同步关联最近的插槽承载者。Leaf 的 `inject()` 能取得 Provider 提供的原始对象、ref 和方法；点击调用 action 会更新双方共享状态。具名、普通节点包裹、嵌套和多实例场景遵循同一规则，卸载重建不会沿用旧上下文。
+
+这条协议不新增包装节点，不复制注入值，不修改原生 `Component.export` / `selectOwnerComponent()`。显式 `setupLifecycle: 'created'` 或 attached 前的公开实例恢复仍按原时机执行 setup，不提供该保证；未经 Wevu 编译的原生/第三方组件也不自动成为注入承载者。
+
+内层 Wevu Provider 即使使用过滤后的 `export()` / `expose()`，其普通模板子组件（含 Options API 局部注册别名）和原生插槽子组件仍共享内层上下文；外部选择器只看到该 Provider 的公开导出，内部父链不依赖公开导出对象。
+
+已验证环境：微信 DevTools Stable `2.02.2608080`（基础库 `3.17.2`、`3.13.2`）和 `2.02.2608060`（基础库 `3.17.2`），并保留 mpcore 回归；这些结果不代替其他版本组合或真机验证。其他小程序平台及 Web 目标不启用此协议，构建时裁剪其声明属性、事件接收与清理代码，不能由微信或 headless 结果推断支持。`false` / augmented 和实际 scoped props 继续使用既有增强插槽路径。
+
 ## 具名插槽透传 wrapper
 
 当你把当前组件的 `<slot />` 转发到子组件的具名插槽时：
@@ -350,3 +362,10 @@ defineOptions({ behaviors: [i18n.behavior] })
 - 需要更完整的编辑器提示说明：[`../volar.md`](../volar.md)
 - 需要运行时页面/组件/store 约束：[`wevu-authoring.md`](./wevu-authoring.md)
 - 需要项目级 `weapp` 配置：[`weapp-config.md`](./weapp-config.md)
+
+
+## JSON 合并读取页面声明
+
+`weapp.json.mergeStrategy(target, source, ctx)` 可读取当前 SFC 页面的 `ctx.routeConfig`（`definePage` 的静态 `{ name, meta }`）和 `ctx.pageMeta`（`definePageMeta` 的完整静态对象）。元信息支持内联、外部脚本与规范导入别名，并贯穿编译阶段、`emit`、`merge-existing` 和 JSON-only HMR。
+
+可按 `typeof ctx.routeConfig?.meta?.title === 'string'` 映射 `navigationBarTitleText`。`pageMeta` 含动态变量、调用、展开或访问器时整个字段为 `undefined`；编译器不会执行表达式或返回部分对象。无声明以及非页面组件不提供这些字段。已有非法路由声明诊断保持有效。