环境与依赖

本页列出「能跑起来」与「能构建、能测试」分别需要什么。最短路径只需要 Node.js 与 Rust；如果还要构建 Tauri 桌面宿主，则需再准备对应平台的工具链。

一览表

组件	要求	用途	检查方式
Node.js	24.x；开发与测试实测 24.21	Vite 开发服务器、构建脚本、Node 测试项目	node --version
npm	随 Node 提供；使用仓库的 package-lock.json	安装依赖、执行脚本	npm --version
Rust	稳定版 1.82 及以上	Tauri 宿主、acgcore、WASM 构建	rustc --version
Cargo	随 Rust 工具链提供	构建 src-tauri 与 acgcore	cargo --version
wasm32 目标	wasm32-unknown-unknown	把 acgcore 编译为隔离环境使用的 WASM	rustup target list --installed
浏览器	现代浏览器；测试默认用系统 Edge	开发时访问外壳；浏览器测试项目	打开 http://localhost:5173/
Tauri 前置	各平台 C/C++ 工具链与 WebView 运行时	构建桌面或移动宿主	见下文

只有网页开发也需要 Rust

网页端的构建会经 build/acgcore-plugin.ts 把 acgcore 编译成 WASM，因此即使不构建 Tauri 宿主，也需要 Rust 与 wasm32-unknown-unknown。只阅读文档或只运行已构建产物不受此限。

Node.js

开发与测试使用 Node.js 24.x；仓库在 Windows 与 Linux 上实测的是 24.21。package-lock.json 锁定依赖版本，安装时不要混用其他包管理器，也不要在未确认影响前删除锁文件。

node --version
npm --version

如果版本低于 24，npm install 可能仍能完成，但构建与测试结果不受支持，遇到问题时也无法按本文档的环境基线复现。建议先用版本管理器切换到 24.x，再重新安装依赖。

仓库的脚本都通过 npm 执行；不要直接调用 vite、vitest 或 tsc 的全局版本，否则可能用到与本仓库不匹配的主版本。

Rust 与 wasm32

宿主代码用到 Option::is_none_or，因此 Rust 最低要求为 1.82；请使用稳定版工具链，不需要 nightly。acgcore 在构建时以离线方式编译到 wasm32-unknown-unknown，所以必须预先安装该目标。

rustc --version
cargo --version
rustup target list --installed

rustup target list --installed 的输出中应包含：

wasm32-unknown-unknown

若没有，执行：

rustup target add wasm32-unknown-unknown

之后再运行构建。缺少目标时，首次构建会在 acgcore 编译阶段失败，并提示需要 wasm32-unknown-unknown；这不是 npm 依赖问题，重装 node_modules 不会解决。处理办法见故障排查。

离线编译依赖本机缓存

acgcore 的构建命令带 --offline，依赖只取 Cargo.lock 与本机 Cargo 缓存。第一次在全新机器上构建时，如果缓存中没有所需 crate，需要先在可联网环境完成一次依赖获取；之后才能稳定离线构建。

浏览器与测试环境

开发服务器只要求现代浏览器。测试配置另有一条默认路径：npm test 的浏览器项目使用系统 Edge（channel: 'msedge'）的无头模式。因此：

• Windows 上通常已具备 Edge，无需额外安装；
• 没有系统 Edge 的环境（例如部分 WSL 镜像）需要改用 Playwright 自带的浏览器；
• 只想手工体验网页端时，不必为测试浏览器做额外准备。

环境变量	允许值	作用
ADV_TEST_BROWSER	webkit、chromium、firefox	改用 Playwright 自带的对应浏览器
ADV_TEST_HOST	localhost 或回环地址（如 127.0.0.2）	把 web 测试服务改绑到指定回环地址
http_proxy／https_proxy	不设置	本地测试不应经代理访问回环地址

WSL 镜像网络模式下，进程可能连不上自己的 127.0.0.1；此时设 ADV_TEST_HOST=127.0.0.2。若环境自带代理变量，跑测试前先移除，否则浏览器可能连不上本地测试服务。具体命令见安装、运行与构建与故障排查。

Tauri 桌面构建的额外前置

Tauri 2 的桌面构建在 Node 与 Rust 之外还需要平台工具链。下表是通用要求；具体安装包名称与版本以 Tauri 2 官方前置说明为准。

平台	额外前置	说明
Windows	MSVC C++ 构建工具；WebView2 运行时	Windows 11 通常自带 WebView2；精简系统需单独安装
Linux	webkit2gtk 4.1 开发库及常见编译工具	还需要发行版提供的 GTK、Soup 等开发包
macOS	Xcode Command Line Tools	桌面构建与签名链依赖系统工具
Android	Android SDK、NDK、JDK	由 Tauri 2 的 Android 工程使用
iOS	Xcode 与对应 SDK	需要 macOS 与可用的签名配置

桌面调试版的前端产物必须与宿主渠道一致。先构建调试版前端，再以 debug-channel 特性运行宿主：

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

src-tauri/build.rs 会核对前端 rpm.json 的 buildChannel 与编译特性；两者不一致时编译直接失败，而不是在运行时带着错误渠道启动。发布构建则使用 npm run build:release，并且不得带 debug-channel。

磁盘与网络

磁盘

预留数 GB 空间；实际占用依平台、Rust 目标与浏览器而定。主要占用来自：

目录或缓存	内容
node_modules/	前端依赖与构建工具
src-tauri/target/	Tauri 宿主与 Rust 依赖的编译产物
acgcore/target/	WASM 构建产物与 Rust 依赖缓存
Playwright 浏览器缓存	仅在改用 ADV_TEST_BROWSER 时需要

外部包不要放进仓库。网页端只有在 OPFS 与 Web Locks 都可用时才把翻译产物写入站点私有存储（OPFS）；Tauri 端写入应用数据目录的 packs/，暂存目录为 packs-staging/。仓库本身不含任何第三方内容，测试夹具只用自己编的最小数据。

网络

• npm install 需要访问 npm 仓库；src-tauri 的首次 Cargo 构建需要取得锁文件中的 crate。
• acgcore 的构建命令是离线的，但首次仍需本机缓存；全新环境可先在可联网状态完成依赖获取。
• 改用 Playwright 自带浏览器时，需要按 Playwright 的方式安装对应浏览器。
• 跑本地测试前移除 http_proxy／https_proxy；回环地址不应经代理。
• 内置示例与本地装载流程不依赖外部内容服务；在线能力属于后续阶段，当前未实现。

不要把内容或密钥放进仓库

仓库只放框架自己的代码与原创示例。不要提交任何第三方剧本、图像、音频、安装包、私钥或访问凭证。根密钥工具写到仓库外的路径，私钥不打印、不上传。

版本组合与常见误区

误区	实际情况
「Node 22 也能跑，应该没问题」	未按 24.x 验证；遇到构建或测试异常时先切回 24.x
「没有 Rust 也能 npm run dev」	不能；首次构建会编译 acgcore 的 WASM
「5174 是第二个应用窗口」	它是独立源信任页，由外壳以 iframe 嵌入
「系统 Edge 是框架运行必需」	不是；它只是测试配置的默认浏览器
「debug 与 release 产物可以混用」	不行；宿主会核对渠道，混用会被拒绝
「仓库里应该有示例素材」	没有；内置示例是纯剧本数据包，不含图像与音频

下一步

• 安装依赖、启动开发服务器、构建与测试：安装、运行与构建
• 第一次启动会看到什么：首次运行
• 环境问题排查：故障排查
• 安装或测试失败的高频问题：常见问题