安装、运行与构建

本页的命令都来自 package.json 与仓库 README。先确认环境满足环境与依赖，再按下面的顺序执行。

应用标识与已有数据

Weftale 使用应用标识 io.weftale.app，以及新的应用与网页存储命名空间。旧应用目录、存档、信任记录与网页数据保留在原位置，不自动迁移或删除；新构建首次运行不会自动接续旧状态。

命令总表

命令	用途	预期结果
npm install	安装前端依赖	生成或补齐 node_modules/，不修改锁文件版本
npm run dev	启动开发服务器（外壳 + 信任页两个源）	外壳在 5173，信任页源在 5174
npm run dev:editor	以编辑器目标启动开发服务器	打开 /editor.html，RPM 含 Author
npm run build:debug	构建调试版前端	产物在 dist/，渠道为 debug
npm run build:release	构建发布版前端	产物在 dist/，剔除调试通道
npm run build:web -- --shell-origin=… --trust-origin=…	构建网页发布版	需要两个不同的 HTTPS 纯源，输出相对基址与两份 CSP 文件
npm run build:editor	构建编辑器产物	产物在 dist-editor/，默认 debug 渠道
npm run build:editor -- --release	构建发布渠道的编辑器产物	产物在 dist-editor/，渠道为 release
npm test	跑 Node 与浏览器两个测试项目	全部通过；浏览器专用用例在 Node 下跳过
npm run test:node	只跑 Node 项目	单元测试与契约测试通过
npm run test:web	只跑浏览器项目	契约测试与界面测试通过
npm run test:tauri	跑真实宿主的原生契约测试	需要先启动调试版宿主并开放 9437
npm run typecheck	检查两份 TypeScript 配置	无输出即通过
cargo test --manifest-path src-tauri/Cargo.toml --features debug-channel	跑宿主 Rust 测试	测试通过
cargo test --manifest-path acgcore/Cargo.toml --offline	离线跑 acgcore 测试	测试通过
npm run scan:release -- dist/	扫描发布产物中的调试标记	输出「未检出调试标记」，退出码 0

安装依赖

进入框架工程目录后安装：

cd weftale
npm install

仓库提供 package-lock.json。如果依赖安装后出现版本漂移或无法复现的问题，优先用锁文件重装，而不是逐个升级依赖：

npm ci

npm ci 会按锁文件重建 node_modules/，需要已存在锁文件；它不会执行 npm install 的版本求解。两种方式二选一，不要与 pnpm／yarn 混用。

开发服务器

npm run dev

build/dev.mjs 会同时创建两个 Vite 服务器，并都设置 strictPort：

端口	内容	说明
5173	外壳	日常开发入口，打开后进入启动校验与主界面
5174	信任页源	独立源；由外壳以 iframe 嵌入，不单独作为应用入口

终端输出类似：

外壳：http://localhost:5173/   信任页源：http://localhost:5174/

如果端口已被占用，服务器会直接失败，而不是自动换端口。这是有意的：信任页的源在构建配置中固定，端口漂移会破坏独立源关系。处理办法见故障排查。

编辑器目标：

npm run dev:editor

终端输出会变为：

编辑器：http://localhost:5173/editor.html   信任页源：http://localhost:5174/

该命令设置 ADV_BUILD_TARGET=editor，使 RPM 的根插件集合包含 Author。它改变的是构建目标，不是另一个端口。

构建

前端运行时

npm run build:debug
npm run build:release

两条命令都把产物写到 dist/，差别在渠道：

命令	渠道	产物特征
build:debug	debug	含调试通道与开发挂载标记；供本地宿主调试
build:release	release	剔除调试通道与调试标记；用于发布

渠道由 Vite 的 mode 决定，并经编译期常量注入。宿主和前端会互相核对渠道；把 debug 产物配给 release 宿主（或反过来）会握手失败或被拒绝启动。

网页发布

网页发布不使用 build:release 代替专用配置，必须给出外壳与信任页的部署源：

npm run build:web -- --shell-origin=https://game.example --trust-origin=https://trust.example

两个源必须不同、使用 HTTPS 且不带路径；也可用 ADV_WEB_SHELL_ORIGIN 与 ADV_WEB_TRUST_ORIGIN 环境变量提供。构建会把资源基址设为相对路径以支持子路径部署，并在 dist/ 生成 web-shell.csp 与 web-trust.csp；部署方须把它们作为响应头策略下发。build:release 只面向 Tauri，未包含网页源，误用于网页部署会拒绝启动。

编辑器

npm run build:editor
npm run build:editor -- --release

默认输出到 dist-editor/，入口为 editor.html。不带 --release 时是 debug 渠道；带 --release 时按发布条件构建。编辑器产物与运行时产物不要互相覆盖，也不要把 dist-editor/ 当作运行时前端部署。

Tauri 桌面调试

Tauri 宿主读取 ../dist 作为前端产物。先构建调试版前端，再运行带 debug-channel 特性的宿主：

npm run build:debug
cargo run --manifest-path src-tauri/Cargo.toml --features debug-channel

src-tauri/build.rs 会核对前端 rpm.json 的 buildChannel 与 debug-channel 特性是否一致；不一致时编译失败。宿主构建与外部包读取的更多限制见 src-tauri/README.md。

测试

两个测试项目

npm test 等价于按配置依次跑 Node 与浏览器两个项目：

项目	覆盖范围	运行环境
node	test/unit/ 与 test/contract/	Node
web	test/contract/ 与 test/ui/	无头浏览器，默认系统 Edge

浏览器项目会把契约测试在真实浏览器里再跑一遍，并额外跑只在 DOM 中成立的界面测试。Node 项目不包含 test/ui/，所以「跳过」通常表示该用例只属于浏览器项目，而不是测试坏了。

npm test
npm run test:node
npm run test:web

默认浏览器是系统 Edge。没有 Edge 或需要换引擎时：

ADV_TEST_BROWSER=chromium npm run test:web

PowerShell 中改用：

$env:ADV_TEST_BROWSER = 'chromium'
npm run test:web

允许值为 webkit、chromium、firefox；其他值会在配置加载时直接报错。WSL 与代理变量的处理见环境与依赖。

类型检查

npm run typecheck

该命令依次检查 tsconfig.json 与 tsconfig.node.json。成功时没有输出；失败时会列出文件、行号与错误码。类型检查不替代测试，测试也不替代类型检查。

Rust 测试

cargo test --manifest-path src-tauri/Cargo.toml --features debug-channel
cargo test --manifest-path acgcore/Cargo.toml --offline

第一条覆盖宿主的路由、文件守卫、包写出与信任存储等逻辑；debug-channel 是测试所需特性。第二条在离线模式下跑 acgcore，依赖锁文件与本机缓存。

真实宿主测试

npm run test:tauri

这不是一条独立的浏览器测试命令。它通过 test/host/native.config.ts 复用已启动的调试版宿主，由 Playwright 连接 WebView 的远程调试端口 9437，把契约测试页载入宿主执行。运行前需要：

1. 构建并启动调试版宿主；
2. Windows 的 debug-channel 构建已自动开放 WebView2 远程调试端口 9437；其他 WebView 仍须按平台准备调试连接，正式渠道不开放该端口；
3. 保持应用处于可启动状态，再由测试脚本接管页面。

脚本找不到宿主时会报「未找到待测试的 Tauri 外壳」。具体脚本与限制见 test/host/ 与故障排查。

发布扫描

发布前扫描前端产物或宿主二进制，确认调试标记没有进入发布物：

npm run build:release
npm run scan:release -- dist/

扫描器检查两个标记：

标记	来源
__ADV_DEV_ONLY_MOUNT__	前端开发挂载标记
ADV-DEBUG-ROUTE-MARKER	Rust 调试路由标记

全部干净时输出「未检出调试标记」并返回 0；命中时把文件与标记打印到标准错误并返回 1。宿主二进制构建完成后，也应把实际二进制路径传给同一命令再扫一遍；不要只扫 dist/ 就认为发布物干净。

不要用排除规则掩盖命中

如果扫描命中，先查明调试代码为什么进入产物（错误渠道、 stale 产物、手工复制、source map 等），再重新构建。给扫描器加排除项只会让发布检查失去意义。

推荐执行顺序

日常开发：npm install -> npm run dev -> npm run typecheck -> npm test
提交前：npm run typecheck -> npm test ->（动了 src-tauri）cargo test ... --features debug-channel
发布前：npm run build:release -> npm run scan:release -- dist/ -> 构建宿主二进制 -> 再扫二进制

更细的症状对照见故障排查；命令之外的安装问题见常见问题。