本地开发与桌面版构建

本页说明 OneDocs 的本地开发入口、Web 前端构建流程，以及基于 Tauri v2 的桌面版开发与发行构建方式。内容以仓库中实际声明的 npm scripts、依赖版本和 README 操作为准。

Purpose and Scope

本页覆盖以下范围：

• 使用 npm install 准备 JavaScript/TypeScript 与 Tauri CLI 依赖。
• 使用 Vite 启动 Web 开发环境，以及使用 Tauri CLI 启动桌面开发环境。
• 使用 npm run build 完成 TypeScript 检查和 Web 生产构建。
• 使用 npm run tauri:build 或 npx tauri build --bundles nsis 生成桌面发行包。
• 桌面构建产物的仓库内输出位置，以及 Tauri/npm 版本配套约束。

本页不展开 React 页面、状态管理、文件读写插件实现，也不覆盖 Android APK 的完整签名与发布流程；Android 相关步骤在仓库 README 中指向独立的 docs/BUILD_ANDROID.md。同样，Tauri 配置文件的具体窗口、权限和打包元数据不在当前已验证的源材料范围内，因此不对这些细节作推断。

Overview

仓库把前端开发和桌面壳开发统一在 npm scripts 中：dev 直接调用 Vite，build 先执行 tsc 再执行 vite build，而 tauri:dev 与 tauri:build 分别调用 Tauri CLI 的开发和构建命令。这样做的关键设计意图是让前端生产构建与桌面打包保持清晰边界：前者负责生成 Web 资源，后者负责将应用纳入 Tauri 桌面发行流程。

桌面端技术栈是 Tauri v2（Rust 壳）与 React/TypeScript 前端。README 将 Tauri API/CLI 固定为 2.6.0，Rust 侧 tauri/tauri-build 固定为 =2.6.0，并列出 tauri-runtime =2.9.2 以及插件版本约束。升级 Tauri 时，README 明确要求 npm 与 Rust 端保持同一代版本并重新验证，这意味着版本协调是桌面构建可重复性的组成部分，而不是可忽略的实现细节。

Architecture

Source: package.json Source: README.md

图中的关系直接对应 package.json 的 scripts，以及 README 对工具链和输出目录的描述。npm run build 的顺序明确是 tsc && vite build：TypeScript 检查失败时，Vite 构建不会继续；桌面开发和桌面发行则由 Tauri CLI 入口负责。README 同时把桌面壳标记为 Tauri v2，把前端标记为 React 19 + TypeScript，把构建工具标记为 Vite 7。

开发与构建边界

Web 前端开发

npm run dev 映射到 vite，因此它是 Web 前端开发服务器入口。这个入口适合只验证前端界面与浏览器侧行为的场景；它并不等价于桌面壳开发，因为 package script 中另有独立的 tauri:dev。

桌面端开发

npm run tauri:dev 映射到 tauri dev。README 将其描述为 Tauri 桌面端开发命令，并要求本地具备 Rust 与 Tauri CLI 工具链。桌面调试应优先使用此入口，而不是把浏览器开发服务器当作桌面运行环境。

Web 生产构建

npm run build 映射到 tsc && vite build，包含两个串行阶段：

1. tsc 执行 TypeScript 检查。
2. 只有检查成功后，vite build 才生成 Web 生产资源。

这种串行写法把类型错误拦截在打包之前，避免将无法通过类型检查的前端代码直接交给后续发布流程。

桌面发行构建

npm run tauri:build 映射到 tauri build，用于构建桌面发行包。README 给出的默认示例注明该命令生成 NSIS + MSI；如果只需要 Windows NSIS，则可运行 npx tauri build --bundles nsis。构建产物位于 src-tauri/target/release/bundle/。

Source: package.json Source: README.md

该顺序只表达仓库已确认的命令调用关系；源码未提供更细的 Tauri 内部打包阶段，因此不进一步假设 Rust 编译、资源复制或安装器生成的内部步骤。

版本与依赖约束

README 要求使用当前仓库已经验证的精确版本组合，不建议在桌面构建链中随意替换为其他版本。已确认的关键版本如下：

package.json 中的 npm 依赖使用 semver 范围，而 README 对 Tauri 相关组合提出“精确版本”要求；因此发布前应以仓库锁定文件和 Rust 端清单为最终解析结果，并遵守 README 的跨端版本配套要求。

Core Flow

首次准备

README 给出的桌面开发最小路径是先安装依赖，再选择 Web 或桌面入口。由于 @tauri-apps/cli 位于 devDependencies，npm install 是调用本地 tauri script 的前置条件。

Source: README.md

Web 构建到桌面打包

如果目标是桌面发行版，推荐把流程理解为两个可独立诊断的阶段：先确认前端生产构建可以通过，再执行 Tauri 打包。仓库本身将二者暴露为不同 script；其中 npm run build 的实际定义是 tsc && vite build，而 npm run tauri:build 的实际定义是 tauri build。

Source: package.json

建议的诊断顺序如下：

1. 若 npm install 失败，先处理 Node/npm 依赖安装问题；此时尚未进入 TypeScript、Vite 或 Rust 构建阶段。
2. 若 npm run build 失败，先区分 tsc 类型检查失败还是 vite build 失败。由于两者由 && 串联，前者失败时不会执行后者。
3. 若 Web 构建成功但 npm run tauri:dev 或 npm run tauri:build 失败，应转向 Rust/Tauri CLI/toolchain 检查；README 明确把 Rust + Tauri CLI 列为桌面前置条件。
4. 若构建成功但找不到安装包，检查 README 指定的 src-tauri/target/release/bundle/ 目录，而不是只检查 Web 构建目录。

选择发行包格式

README 提供两种已验证的桌面发行命令：默认构建 NSIS + MSI，或显式只构建 NSIS。后者适合只需要 Windows NSIS 安装器的场景，可减少不需要的 bundle 类型。

Source: README.md

Usage Examples

直接使用 npm scripts

以下是仓库实际定义的完整本地开发与构建入口；脚本名保持不变，以便与 CI 或团队操作约定一致。

Source: package.json

使用 CLI 只构建 NSIS

这是 README 明确给出的高级桌面构建用法。它绕过 npm script，直接使用项目本地可用的 Tauri CLI，并通过 --bundles nsis 限定发行包类型。

Source: README.md

Configuration Options

当前已验证的构建配置主要来自 package.json scripts 与 README 的工具链约束。Tauri 配置文件没有在本页的可用源材料中成功读取，因此不列出窗口尺寸、权限、应用标识或 bundle 元数据等未验证选项。

API Reference

本页的“API”是仓库对开发者暴露的命令入口，而不是应用业务 HTTP API。

npm run dev

调用 vite，用于 Web 前端开发。仓库没有在已读材料中声明额外参数或端口覆盖，因此不对默认端口作推断。

npm run build

调用 tsc && vite build。

• 输入： 当前工作区中的 TypeScript/Vite 项目。
• 返回/结果： 成功时生成 Web 生产资源。
• 失败行为： tsc 非零退出会阻止 vite build 执行；Vite 阶段错误则使整个 npm script 失败。

npm run tauri:dev

调用 tauri dev，用于启动桌面开发模式。

• 前置条件： 已安装 npm 依赖，并具备 Rust 与 Tauri CLI 工具链。
• 结果： 启动 Tauri 桌面开发环境。
• 异常信息： 仓库已确认需要 Rust + Tauri CLI，但当前材料未提供更细的错误类型或恢复策略。

npm run tauri:build

调用 tauri build，用于桌面发行构建。

• 结果： README 说明默认示例生成 NSIS + MSI，产物位于 src-tauri/target/release/bundle/。
• 替代调用： npx tauri build --bundles nsis 只构建 NSIS。
• 版本约束： README 要求 npm 与 Rust 端使用同一代 Tauri 版本并重新验证。

Failure Modes, Edge Cases & Concurrency

已确认的失败边界

• 依赖未安装： tauri CLI 位于开发依赖中；没有完成 npm install 时，脚本可能无法找到本地命令。
• 类型检查失败： npm run build 使用 shell 的 && 连接 tsc 与 vite build，所以类型检查失败会短路后续 Vite 构建。
• 桌面工具链缺失： README 把 Rust + Tauri CLI 标为桌面要求；这类问题属于环境准备阶段，而非业务代码失败。
• 版本漂移： README 要求 Tauri npm 与 Rust 侧保持同一代并重新验证。跨代混用是已明确指出的风险边界。
• 输出目录误判： 桌面产物应在 src-tauri/target/release/bundle/ 查找；Web 资源和桌面 bundle 不应混为同一输出。

并发与可重复性

已读源代码没有发现构建脚本自行启动并发任务、共享锁或自定义缓存协调逻辑。可以确认的是，npm run build 内部是顺序执行的 tsc 后接 vite build。更深层的并发行为属于 npm、Vite、Rust/Cargo 或 Tauri CLI 内部实现，当前源材料不足以作出仓库级结论。

Performance and Operational Notes

• 只进行前端开发时使用 npm run dev，可以避免不必要地启动桌面壳。
• 需要验证桌面集成时使用 npm run tauri:dev，不要把 Web 开发服务器结果当作桌面运行结果。
• 发行前可先运行 npm run build，将 TypeScript/Vite 问题与 Rust/Tauri 打包问题分层定位。
• 只需要 NSIS 时使用 --bundles nsis，这是 README 标注的推荐变体。
• 发布环境应保存并复核 Tauri npm/Rust 版本组合；README 明确要求升级时重新验证。

Extension Points

当前构建系统的明确扩展点是 package.json scripts：可以在不改变工具链调用方式的前提下，为团队增加经过验证的 npm 入口。不过，仓库现有材料没有定义自定义构建钩子、Tauri 配置扩展协议或 CI 发布流水线，因此不应据此推断存在可直接复用的扩展接口。

Android scripts（android:init、android:dev、android:build、android:build:split、android:build:signed）属于同一 package script 表，但本页只做边界说明；README 将详细 Android 步骤放在 docs/BUILD_ANDROID.md，不在本桌面版页面中展开。

Related Links

• README.md — 开发、桌面构建与输出目录
• package.json — npm scripts 与 Tauri 依赖
• AGENTS.md — 仓库开发命令摘要
• docs/BUILD_ANDROID.md — Android 构建说明（README 指向）