weapp-vite 7.3.0 → 7.4.0

package/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/adapters-BwnMMIZR.mjs

@@ -0,0 +1,2 @@
+import { MINI_PROGRAM_PLATFORM_DESCRIPTORS as MINI_PROGRAM_PLATFORM_ADAPTERS } from "@weapp-core/shared";
+export { MINI_PROGRAM_PLATFORM_ADAPTERS as t };

package/dist/auto-routes.mjs

@@ -1,4 +1,4 @@
-import { n as getCompilerContext, y as getRouteRuntimeGlobalKeys } from "./createContext-cqr9Y4EV.mjs";
+import { n as getCompilerContext, y as getRouteRuntimeGlobalKeys } from "./createContext-UOEgeYnA.mjs";
 //#region src/auto-routes.ts
 const ROUTE_RUNTIME_OVERRIDE_KEY = Symbol.for("weapp-vite.route-runtime");
 function createGetter(resolver) {