企业官网建设流程全解析

• 桌面应用

本文基于仓库根目录 CONTRIBUTING.md 贡献指南展开，为想要参与 Sigma File Manager（Windows / Linux 平台的现代开源文件管理器）开发，或希望直接从源码编译运行该应用的开发者，提供一套完整可落地的实战流程：包括 Node.js / Rust 环境准备、克隆与依赖安装、npm run tauri:dev调试运行、Linux 图形问题规避、npm run check质量门禁，以及npm run tauri:build构建验证。读完本文，你将掌握从零搭建开发环境到通过完整校验并产出安装包的端到端能力。

一、贡献前的第一原则：先讨论，再动手

CONTRIBUTING.md 在开头就给出了一条硬性规则：在实现任何改动之前，请先创建一个 issue / discussion 进行讨论，由维护者与社区共同评估该功能是否应该加入，之后再进入编码阶段。

⚠️ Before you implement any changes, create a new issue / discussion so we can discuss it first and decide if we should add it.

这条规则的意义在于：Sigma File Manager 迭代速度很快、功能面非常广（导航、扩展、全局搜索、LAN 共享、标签页、快捷视图等），先对齐需求可以避免“辛苦实现的功能被拒绝合并”的返工成本。同时，贡献指南也明确说明：本指南不仅面向贡献者，也适用于只是想以开发模式运行应用的人——如果你打算从源码体验最新功能或排查问题，下面的流程同样适用。

二、前置条件：Node.js 与 Rust 工具链

2.1 Node.js 版本要求（以engines.node为准）

按 package.json 中的声明，项目要求：

"engines": { "node": ">=24.16.0" }, "volta": { "node": "24.16.0" }

• engines.node是权威依据：Node.js 版本必须>= 24.16.0；
• 仓库同时使用 Volta 将工具链固定到24.16.0（volta.node字段），如果你使用 Volta，它会自动切换到该版本；
• 也可以用nvm等版本管理工具执行nvm use（配合.nvmrc类配置）或手动切换到满足要求的版本，指南中的第 1 步“Switch to requiredNodeversion”指的就是这一步。

2.2 Rust 与平台依赖

前端之外，桌面外壳由 Tauri 2 驱动，因此需要安装 Rust 以及对应平台所需的系统库。仓库 src-tauri/Cargo.toml 记录了最低支持版本：

edition = "2021" rust-version = "1.88.0"

即 Rust 版本需不低于1.88.0。CONTRIBUTING.md 建议按 Tauri 官方前置条件指南（Prerequisites）安装对应平台的依赖（Linux 上通常包括 WebKitGTK 等构建库；Windows 上主要是 MSVC 工具链与 WebView2）。以当前仓库的实际配置看，Linux 桌面端依赖 WebKitGTK 渲染，Windows 端依赖 WebView2，这些都在 Tauri 官方前置条件文档中有说明。

2.3 技术栈速览（便于理解构建流程）

在动手之前，先大致了解仓库的技术构成，有助于理解后续命令的作用：

• 前端：Vue 3 + TypeScript + Vite（入口见 src/main.ts，路由见 src/router/index.ts），状态管理使用 Pinia，国际化使用 vue-i18n（语言包位于 src/localization/messages）；
• 桌面层：Tauri 2（版本约束见 src-tauri/Cargo.toml 的tauri = { version = "2.11", ... }），后端 Rust 代码集中在 src-tauri/src，入口为 src-tauri/src/main.rs 与 src-tauri/src/lib.rs；
• 配置：桌面窗口、构建产物与开发服务器地址统一在 src-tauri/tauri.conf.json 中管理。

三、从克隆到跑起开发模式：完整步骤

以下是 CONTRIBUTING.md 给出的标准流程，结合仓库源码逐条展开。

3.1 Fork 项目并克隆，切换到 main 分支

cd sigma-file-manager git switch main

建议先 Fork 上游仓库再克隆自己的副本，便于后续通过 Pull Request 提交改动。

3.2 安装依赖

npm i

仓库使用 npm 作为包管理器（根目录存在 package-lock.json 与 e2e-webdriver/package-lock.json），依赖体量较大（Vue、Reka UI、Pinia、Tauri CLI 等，见 package.json），首次安装耗时较长属正常现象。

3.3 配置本地 git 身份

如果未使用全局 git config，需要为本仓库单独配置提交者身份：

git config user.name "Your Name Here" git config user.email your@email.example

3.4 启动开发模式

npm run tauri:dev

这条命令实际执行的是（见 package.json）：

npm run sync-version && tauri dev

• sync-version调用 scripts/sync-version.js：把 package.json 中的version同步写入 src-tauri/Cargo.toml、default-file-manager-common/Cargo.toml与default-file-manager-launcher/Cargo.toml三个 Cargo 清单，保证前后端版本号一致（该脚本仅在版本不一致时才写入，并打印Synced N Cargo manifests to <version>）；
• tauri dev读取 src-tauri/tauri.conf.json 的配置：beforeDevCommand为npm run dev（启动 Vite），devUrl为http://localhost:1420，前端 dev 服务器与 Rust 后端建立调试连接。

Vite 开发服务器的细节在 vite.config.ts 中可见：

server: { port: 1420, strictPort: true, host: host || false, // host 取自环境变量 TAURI_DEV_HOST hmr: host ? { protocol: 'ws', host, port: 1421 } : undefined, watch: { ignored: ['**/src-tauri/target/**', '**/node_modules/**'] }, }

• 端口固定为1420（strictPort: true，端口被占用会直接报错而不是换端口）；
• 若设置了TAURI_DEV_HOST（在移动端或远程设备调试场景），HMR 走 WebSocket 端口1421；
• 另外 vite.config.ts 通过vite-plugin-run注册了两个监听任务：修改src/**/*.{vue,ts,js}或src-tauri/src/**/*.rs时自动执行sync-license（同步许可证头），修改src/localization/messages/en.json时自动执行sync-i18n（同步各语言包），开发过程中无需手动干预。

3.5 Linux 视觉异常时的替代命令

在 Linux 上如果看到渲染异常（详见下文“已知问题”一节），改用：

npm run tauri:dev:webkit-igpu

该脚本等价于（见 package.json）：

npm run sync-version && env WEBKIT_DISABLE_COMPOSITING_MODE=1 tauri dev

即关闭 WebKitGTK 的合成（compositing）模式后再启动开发模式，用于规避私有显卡驱动下的花屏、黑块等问题。

3.6 实现改动：仅在讨论通过后进行

在 issue / discussion 被接受之前不要进入编码阶段。仓库对代码风格有非常严格的约束（详见第五节），因此实现时请遵循现有代码的组织方式，例如：

• 前端业务模块按领域划分，位于 src/modules（navigator、settings、extensions、home等）；
• 可复用的跨模块逻辑放入 src/composables 与 src/utils；
• 运行时状态（Pinia store）集中在 src/stores/runtime；
• Rust 后端按能力拆分为独立模块（dir_reader、file_operations、global_search、lan_share、extensions等），并在 src-tauri/src/lib.rs 通过invoke_handler统一注册为 Tauri 命令。

四、保持同步：频繁拉取上游更新

Sigma File Manager 代码更新频繁，CONTRIBUTING.md 特别提醒在提交改动或运行/构建应用之前，先拉取最新代码、按需重装依赖并解决冲突：

git pull && npm i

依赖清单（package.json的dependencies/devDependencies）可能随上游更新而变化，因此npm i是必须的，不能省略。

五、提交前质量门禁：npm run check

在提交改动之前，必须运行仓库统一的质量检查脚本：

npm run check

查看 package.json，它等价于并行执行三组任务（run-p表示并行）：

run-p ts lint:check test:unit:run

拆开来看：

5.1 类型检查：ts

"ts": "vue-tsc --build"（见 package.json），基于 tsconfig.json 的 project references 结构（tsconfig.node.json、tsconfig.app.json、tsconfig.vitest.json）对 Vue 单文件组件与 TypeScript 代码做全量类型检查。

5.2 代码规范：lint:check

lint:check串行执行 ESLint 与 Stylelint 检查（run-s lint:*:check）：

• lint:eslint:check：eslint . --max-warnings 0，任何 warning 都视为失败。规则定义在 eslint.config.ts，要点包括：
  • 集成 Vue、TypeScript（@vue/eslint-config-typescript）、Vitest（仅对src/**/__tests__/*启用）与 vue-i18n 插件；
  • 强制函数声明风格（func-style）、对象属性换行与花括号内空格等 Stylistic 规则；
  • 文件名与目录名必须使用 KEBAB_CASE（check-file/filename-naming-convention与folder-naming-convention，__tests__目录除外）；
  • 所有.vue文件禁止出现未国际化硬编码文本（@intlify/vue-i18n/no-raw-text，仅允许 Alt/Ctrl/Shift/Enter 等白名单文本）。
• lint:stylelint:check：stylelint "src/**/*.{css,vue}" --max-warnings 0，样式规范见根目录 stylelint 相关配置（BEM 命名、属性排序、CSS Modules 兼容等）。

5.3 单元测试：test:unit:run

test:unit:run通过 scripts/vitest-run.mjs 调用本地node_modules/vitest执行测试（该包装脚本兼容 Windows 盘符路径大小写问题）。测试配置见 vitest.config.ts：

test: { environment: 'jsdom', exclude: [...configDefaults.exclude, 'e2e/**'], setupFiles: [fileURLToPath(new URL('./src/test-support/vitest-setup.ts', import.meta.url))], }

• 使用 jsdom 模拟 DOM，便于测试 Vue 组件与 composables；
• 仓库已内置大量单元测试，例如 src/composables/tests、src/stores/runtime/tests、src/utils/tests等目录下的*.test.ts文件；新增功能时建议同步补充测试，这是通过npm run check的组成部分。

5.4 可选的 E2E 测试（Windows 全量检查）

在 Windows 上，仓库还提供了check:win（run-p ts lint:check test:unit:run test:e2e:webdriver），包含 WebDriver 端到端测试：

npm run test:e2e:webdriver

配置见 e2e-webdriver/wdio.conf.js：默认会先执行npm run tauri -- build --debug --no-bundle构建调试版应用，再通过tauri-driver（位于~/.cargo/bin）驱动被测应用；Windows 上还会通过install-edge-driver脚本解析并传入 Edge 原生驱动（见 e2e-webdriver/scripts/install-edge-driver.mjs）。测试规格存放在 e2e-webdriver/test/specs，例如 nav-sidebar.e2e.js 会逐一点击侧边栏并断言路由跳转。

如果已经手动构建过调试版应用，可设置环境变量跳过重复构建：

SFM_SKIP_TAURI_BUILD_FOR_WEBDRIVER=1 npm run test:e2e:webdriver:skip-build

六、构建验证：npm run tauri:build

代码通过质量检查后，还需要验证构建没有问题：

npm run tauri:build

6.1 命令链路

tauri:build等价于（见 package.json）：

npm run sync-version && tauri build

tauri build会依次执行 src-tauri/tauri.conf.json 中定义的beforeBuildCommand（npm run build，即 Vite 生产构建到dist/目录），随后编译 Rust 后端并打包安装程序，frontendDist指向../dist。

6.2 Vite 生产构建配置

正如 CONTRIBUTING.md 所说，构建可以在 ./vite.config.ts 中配置，关键点包括：

• 路径别名：@指向./src，@shared指向./src-shared（vite.config.ts）；
• 构建目标：Windows 平台为chrome138，其他平台为safari17（vite.config.ts）；
• 压缩与 SourceMap：非调试环境用esbuild压缩且不生成 sourcemap；调试环境（TAURI_ENV_DEBUG）保留 sourcemap 且不压缩（vite.config.ts）；
• 构建守卫插件：rejectTestModulesInProductionBuild会阻止测试模块进入生产构建，backgroundSourceImportGuard限制受限的背景资源导入（vite.config.ts）。

6.3 打包目标与版本号

src-tauri/tauri.conf.json 声明了打包目标：nsis（Windows 安装器）、appimage、deb、app、dmg；应用标识为com.sigma-file-manager.app，主窗口尺寸默认 1280×720（最小 500×300）。Linux 下如需完整打包，还可以使用：

npm run tauri:build:linux

该脚本额外设置了NO_STRIP=true（见 package.json），避免 strip 符号导致某些发行版运行异常。此外仓库还提供了 Flatpak 打包脚本flatpak:build（对应 flatpak/com.sigma-file-manager.app.yml）以及 Snap 清单 snap/snapcraft.yaml，供打包分发时参考。

6.4 版本号一致性

sync-version脚本（scripts/sync-version.js）会把 package.json 的version同步到 src-tauri/Cargo.toml、default-file-manager-common/Cargo.toml、default-file-manager-launcher/Cargo.toml三处（当前版本为2.2.0）。因此不要在只改一处版本号后直接提交——正式流程总是通过sync-version统一推进。

七、Linux 已知问题与解决方案

CONTRIBUTING.md 记录了开发与运行中常见的一类问题：

在私有 Nvidia（或不支持的）显卡驱动上运行，可能会遇到各种视觉问题。

7.1 开发模式

按 3.5 节使用：

npm run tauri:dev:webkit-igpu

7.2 运行 AppImage 安装包

在驱动不受支持的 Linux 系统上运行 AppImage 构建产物时，通过环境变量关闭 WebKit 合成模式：

env WEBKIT_DISABLE_COMPOSITING_MODE=1 ./{FILE_NAME}.AppImage

其中{FILE_NAME}替换为实际 AppImage 文件名。该方案同样适用于其他分发包（deb / flatpak 等）在异常驱动环境下的渲染问题排查，本质是让 WebKitGTK 走软件合成路径，规避 GPU 合成层在私有驱动下的缺陷。

八、贡献后的完整闭环

把上述步骤串起来，一次符合规范的贡献流程是：

1. 在 issue / discussion 中提出并确认改动方案；
2. 切到 Node >= 24.16.0 环境，git switch main并npm i；
3. 配置本地 git 身份，创建功能分支开始实现；
4. 用npm run tauri:dev（Linux 视觉异常时用tauri:dev:webkit-igpu）本地调试；
5. 提交前git pull && npm i同步上游，解决冲突；
6. 运行npm run check通过类型检查、Lint 与单元测试（Windows 上可加跑check:win含 E2E）；
7. 运行npm run tauri:build验证生产构建通过；
8. 提交 Pull Request。

对只想从源码运行最新版本的用户，最低操作路径可以简化为：准备 Node/Rust 环境 →npm i→npm run tauri:dev；对需要分发打包的场景，则补上npm run tauri:build（或tauri:build:linux/flatpak:build）。

更多项目背景、功能清单与安装方式可参阅 README.md，版本演进记录可查看 CHANGELOG.md 与 public/changelog 下的多语言变更日志。

• 桌面应用