企业官网建设流程全解析

HOP 是一款基于 Tauri 2 的开源 HWP/HWPX 文档编辑器，支持 macOS、Windows 与 Linux 三大平台。围绕这个"前端 TypeScript + 后端 Rust + 只读上游引擎"的混合架构，HOP 构建了一套三层测试验证矩阵：仓库级上游契约测试、Studio 层 Vitest 单元测试、以及 Rust 侧的cargo test集成测试。一条pnpm test命令即可全量执行，任何一层失守都会在发布前被拦截。

为什么需要三层验证？

HOP 的产品代码不直接"拥有"文档引擎——它来自只读的上游子模块third_party/rhwp，通过 Vite 别名覆盖（alias override）的方式叠加 HOP 自己的行为。这意味着测试不仅要验证"功能对不对"，还要验证边界守没守住：

• HOP 的 TypeScript 有没有绕过适配器直接摸上游内部实现？
• 上游版本锁定文件、WASM 产物、Rust 依赖三者是否指向同一个版本？
• 发布版本号在 6 处元数据里是否完全一致？

这些问题无法靠普通的单元测试回答，于是形成了下面这套矩阵。

第一层：上游契约测试（仓库根目录tests/）

🔒 这一层由 Node.js 原生测试运行器驱动，入口是 package.json 中的test:upstream脚本，共 4 个测试文件：

这一层最妙的设计是**"负向断言"**：比如断言 apps/studio-host/src/main.ts 中不出现危险修复路径、断言某些本地 fork 文件必须"不存在"——用测试钉死"我们没有偷偷 fork 上游"这件事。架构文档见 docs/architecture/UPSTREAM.md。

第二层：Studio 单元测试（Vitest）

🧩 编辑器前端（studio-host）使用 Vitest 运行，配置在 apps/studio-host/vitest.config.ts。测试文件共 22 个，以src/**/*.test.ts模式匹配，例如：

• 桥接层：tauri-bridge.test.ts 通过 mock Tauri API，验证打开/保存/打印等原生调用的编排逻辑，无需真实系统弹窗；
• 文件分块读写：chunked-fs.test.ts 验证大文档分块传输与字节哈希；
• 命令与快捷键：file.test.ts、shortcut-map.test.ts 保证桌面端文件命令和键位映射行为稳定；
• UI 组件：对话框、工具栏、更新提示等均有独立测试（如 update-notice.test.ts）。

Vitest 的resolve.alias与生产构建完全同构（@upstream指向只读上游源码），因此单测跑的是"真实依赖图"，而不是沙盒世界。

第三层：Rust 集成测试（cargo test）

⚙️ 桌面壳与 macOS Quick Look 扩展的 Rust 代码各有集成测试：

• 桌面端（test:desktop脚本，即 apps/desktop/src-tauri 下的cargo test）：包含 linux_runtime.rs 集成测试入口，以及 linux_runtime_tests/ 中针对 GTK/Qt 输入法环境变量、Wayland 检测等跨平台细节的用例——测试会先捕获环境、跑完再恢复，避免用例互相污染；
• Quick Look 扩展（test:quicklook:macos脚本）：由 scripts/test-quicklook-macos.mjs 在非 macOS 平台自动跳过，在 macOS 上以--locked加 native-skia 特性运行 tests.rs，覆盖空输入、非法文档、缺失缩略图等 FFI 边界场景，并用真实样例 HWP 文件验证 PDF 首字节签名。

全仓 Rust 测试用例超过 87 个，配合 AGENTS.md 中要求的cargo clippy -- -D warnings，静态检查与行为验证双保险。

一键运行：完整验证矩阵 🚀

在仓库根目录执行一条命令，即可按顺序跑完四层检查：

pnpm test

它等价于依次执行test:upstream → test:studio → test:desktop → test:quicklook:macos。发布前的完整流程还包括pnpm run build:studio与 debug 包构建，详见 docs/DEVELOPMENT.md。

这套体系给个人的启示

1. 契约即测试：把"架构不许越界"写成可执行断言，比文档约定更可靠；
2. 单一事实来源：版本号、上游基线各有一份锁文件，其余位置全部由测试比对；
3. 分层聚焦：日常开发先跑最聚焦的一层（AGENTS.md明确建议），全量矩阵留给发布关卡。

想深入上游更新与验证细节，可继续阅读 docs/operations/RHWP_UPDATE.md 与 scripts/lib/rhwp-upstream.mjs 中的契约工具函数。