BuildGuide

构建指南

本指南介绍如何从源码构建 Zephyr。Zephyr 是基于 Tauri v2 的 Mihomo GUI 代理客户端，前端使用 Vanilla JavaScript，后端使用 Rust。

项目结构

Zephyr 采用前后端分离的架构，前端与 Rust 后端通过 Tauri IPC 通信：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}}}%%
graph TB
    subgraph 根目录
        A["package.json<br/>项目配置"]
        B[".semgrep.yml<br/>Semgrep 规则配置"]
        C["tailwind.config.js<br/>Tailwind CSS 配置"]
        D["eslint.config.js<br/>ESLint 配置"]
    end

    subgraph src["apps/desktop/src/ - 前端模块"]
        E["apps/desktop/src/main.js<br/>应用入口"]
        F["apps/desktop/src/api.js<br/>IPC 桥接 + API"]
        G["apps/desktop/src/websocket.js<br/>HTTP Streaming"]
        H["apps/desktop/src/i18n.js<br/>国际化"]
        I["apps/desktop/src/rules.js<br/>规则转换"]
        I2["apps/desktop/src/modules/connections.js<br/>连接监控"]
        I3["apps/desktop/src/modules/traffic-chart.js<br/>流量图表"]
        J["apps/desktop/src/ui/<br/>29 个 UI 模块"]
        K["apps/desktop/src/utils/<br/>14 个工具模块"]
        L["apps/desktop/src/index.html<br/>HTML 入口"]
        M["apps/desktop/src/styles.css<br/>样式源文件"]
    end

    subgraph shared["packages/ - 共享包"]
        S1["packages/shared/<br/>命令名常量 (COMMANDS)"]
        S2["packages/scripts/<br/>i18n 检查器"]
    end

    subgraph srcTauri["apps/desktop/src-tauri/ - Rust 后端模块"]
        N["apps/desktop/src-tauri/Cargo.toml<br/>Rust 依赖配置"]
        O["apps/desktop/src-tauri/src/main.rs<br/>Rust 入口"]
        P["apps/desktop/src-tauri/src/lib.rs<br/>库入口"]
        Q["apps/desktop/src-tauri/src/core_manager.rs<br/>→ core/ 模块门面"]
        Q2["apps/desktop/src-tauri/src/core/<br/>9 个子模块"]
        R["apps/desktop/src-tauri/src/deep_link.rs<br/>Deep Link"]
        S["apps/desktop/src-tauri/src/global_shortcut.rs<br/>全局快捷键"]
        T["apps/desktop/src-tauri/src/os_notification.rs<br/>系统通知"]
        U["apps/desktop/src-tauri/src/config_manager.rs<br/>配置管理"]
        V["apps/desktop/src-tauri/src/sys_proxy.rs<br/>系统代理"]
        W["apps/desktop/src-tauri/src/tray.rs<br/>系统托盘"]
        X["apps/desktop/src-tauri/src/updater.rs<br/>自动更新"]
        Y["apps/desktop/src-tauri/src/uwp_loopback.rs<br/>UWP 回环"]
        Z["apps/desktop/src-tauri/tauri.conf.json<br/>Tauri 配置"]
        AA["apps/desktop/src-tauri/capabilities/<br/>权限配置"]
    end

    subgraph github[".github/ - CI/CD"]
        BB[".github/workflows/<br/>工作流文件"]
        CC[".github/dependabot.yml<br/>Dependabot 配置"]
        DD[".github/ISSUE_TEMPLATE/<br/>Issue 模板"]
    end

    A --> E
    A --> N
    E --> F
    E --> G
    E --> H
    E --> I
    E --> I2
    E --> I3
    E --> J
    E --> K
    E --> L
    E --> M
    N --> O
    O --> P
    P --> Q
    P --> Q2
    P --> R
    P --> S
    P --> T
    N --> U
    N --> V
    A --> W
    W --> X
    W --> Y

目录说明

目录/文件	说明
`apps/desktop/`	桌面应用主包
`apps/desktop/src/`	Vanilla JavaScript 前端源代码
`apps/desktop/src/main.js`	应用入口，初始化编排，懒加载日志页面
`apps/desktop/src/api.js`	Tauri IPC 桥接层（`__TAURI_INTERNALS__`）+ Mihomo REST API 封装
`apps/desktop/src/websocket.js`	HTTP Streaming 数据推送（fetch + ReadableStream）
`apps/desktop/src/i18n.js`	国际化（i18n）支持（en/zh/ja/ko）
`apps/desktop/src/rules.js`	Shadowrocket 规则转 Clash 规则格式转换
`apps/desktop/src/ui/`	29 个 UI 模块（settings, proxies, logs, advanced, global-shortcut, deep-link, client-updater, os-notification, bind 等）
`apps/desktop/src/utils/`	14 个工具模块（sanitize, logger, format, debounce, throttle, focus-trap, page-visibility, roving-tabindex, sequential, markdown 等）
`apps/desktop/src/modules/`	功能模块（connections 连接监控、traffic-chart 流量图表）
`apps/desktop/src/types/`	TypeScript 声明文件（tauri.d.ts, guards.d.ts）
`apps/desktop/src/index.html`	HTML 入口页面
`apps/desktop/src/styles.css`	Tailwind CSS 样式源文件
`apps/desktop/src-tauri/`	Tauri v2 后端（Rust）
`apps/desktop/src-tauri/src/lib.rs`	Rust 库入口，Tauri 命令注册
`apps/desktop/src-tauri/src/core_manager.rs`	core/ 模块门面（re-export，67 行）
`apps/desktop/src-tauri/src/core/`	9 个子模块（core_process, crypto, subscription, tun_manager, config_manager, config_sanitizer, secure_io, core_log, mod）
`apps/desktop/src-tauri/src/config_manager.rs`	配置文件读写与管理（1011 行）
`apps/desktop/src-tauri/src/sys_proxy.rs`	系统代理、TUN、防火墙等系统交互（961 行）
`apps/desktop/src-tauri/src/tray.rs`	系统托盘菜单与交互
`apps/desktop/src-tauri/src/updater.rs`	内核更新 + 客户端更新
`apps/desktop/src-tauri/src/uwp_loopback.rs`	Windows UWP 回环代理解除
`apps/desktop/src-tauri/capabilities/`	Tauri v2 权限声明文件
`packages/shared/`	共享包（Tauri IPC 命令名常量 SSOT）
`packages/scripts/`	开发脚本（i18n 完整性检查器）
`pnpm-workspace.yaml`	pnpm monorepo 工作区配置
`.github/workflows/`	GitHub Actions CI/CD 工作流
`.semgrep.yml`	Semgrep 静态分析规则配置

开发工作流

从源码构建到开发调试的完整工作流：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A[克隆仓库] --> B[安装前端依赖<br/>npm install]
    B --> C[安装 Rust 工具链<br/>rustup]
    C --> D[安装平台依赖<br/>WebKit2GTK 等]
    D --> E[开发模式运行<br/>npm run tauri dev]
    E --> F{开发阶段}

    F -->|编写前端代码| G[热更新预览<br/>Tauri 热重载]
    F -->|编写后端代码| H[重新编译 Rust<br/>自动重启]

    G --> I[代码检查]
    H --> I

    I --> I1[ESLint 检查<br/>npm run lint]
    I --> I2[Clippy 检查<br/>cargo clippy]
    I --> I3[rustfmt 格式检查<br/>cargo fmt --check]

    I1 --> J[运行测试]
    I2 --> J
    I3 --> J

    J --> J1[Vitest 单元测试<br/>npm run test]

    J1 --> K{所有检查通过?}

    K -->|是| L[提交代码<br/>git commit]
    K -->|否| M[修复问题<br/>返回开发阶段]
    M --> F

    L --> N[推送 PR<br/>CI 自动检查]
    N --> O[代码审查]
    O --> P[合并]

    P --> Q[生产构建<br/>npm run tauri build]
    Q --> R[生成安装包<br/>各平台格式]

环境要求

通用依赖

工具	最低版本	推荐版本	说明
Node.js	18.0	20 LTS	JavaScript 运行时
npm	9.0	10.x	包管理器
Rust	1.75.0	最新稳定版	后端语言
Cargo	与 Rust 同步	与 Rust 同步	Rust 包管理器
Tauri CLI	2.x	最新 2.x	Tauri 命令行工具

安装 Rust 工具链

# 安装 rustup（Rust 工具链管理器）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装完成后，加载环境变量
source $HOME/.cargo/env

# 确认安装成功
rustc --version
cargo --version

# 添加目标平台（如需交叉编译）
rustup target add x86_64-pc-windows-msvc   # Windows
rustup target add x86_64-apple-darwin       # macOS Intel
rustup target add aarch64-apple-darwin      # macOS Apple Silicon
rustup target add x86_64-unknown-linux-gnu  # Linux

安装 Node.js

推荐使用 nvm 或 fnm 管理 Node.js 版本：

# 使用 fnm
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 20
fnm use 20

# 或使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

平台特定依赖

Windows

依赖	安装方式	说明
Visual Studio Build Tools	下载安装	勾选"C++ 桌面开发"
WebView2 SDK	通过 vcpkg 或随 VS 安装	Tauri 依赖
Windows SDK	随 Visual Studio 安装	提供 Windows API
NSIS	`npm install -g nsis`	Windows 安装包生成

# 安装 Windows 构建工具（PowerShell 管理员模式）
npm install -g windows-build-tools

# 或手动安装 Visual Studio Build Tools 2022
# 勾选以下工作负载：
# - C++ 桌面开发
# - Windows 10/11 SDK

macOS

依赖	安装方式	说明
Xcode Command Line Tools	`xcode-select --install`	C/C++ 编译器
Apple Developer Tools	随 Xcode 安装	代码签名和公证
create-dmg	`brew install create-dmg`	DMG 打包

# 安装 Xcode 命令行工具
xcode-select --install

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装额外工具
brew install create-dmg

Linux

依赖	安装方式	说明
libwebkit2gtk-4.1-dev	包管理器	Web 渲染引擎开发包
libgtk-3-dev	包管理器	GTK3 开发库
libayatana-appindicator3-dev	包管理器	系统托盘开发库
librsvg2-dev	包管理器	SVG 渲染开发库
libssl-dev	包管理器	OpenSSL 开发库
patchelf	包管理器	ELF 文件修补工具
file	包管理器	文件类型检测
dpkg / rpm	包管理器	打包工具

Ubuntu / Debian:

sudo apt update
sudo apt install build-essential \
    libwebkit2gtk-4.1-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev \
    libssl-dev \
    patchelf \
    file \
    libxdo-dev \
    libdbus-1-dev

Fedora:

sudo dnf groupinstall "Development Tools"
sudo dnf install webkit2gtk4.1-devel \
    gtk3-devel \
    libappindicator-gtk3-devel \
    librsvg2-devel \
    openssl-devel \
    patchelf \
    file \
    libXdo-devel \
    dbus-devel

Arch Linux:

sudo pacman -S base-devel \
    webkit2gtk-4.1 \
    gtk3 \
    libappindicator-gtk3 \
    librsvg \
    openssl \
    patchelf \
    file \
    libxdo \
    dbus

编译环境

CI 编译环境基于 GitHub Actions，使用 dtolnay/rust-toolchain@stable 和 actions/setup-node@v4 配置工具链。以下为各平台编译环境的详细配置。

工具链配置

组件	Action / 方式	说明
Rust 工具链	`dtolnay/rust-toolchain@stable`	安装最新稳定版 Rust
Node.js	`actions/setup-node@v4`	安装 Node.js 运行时
Linux 系统依赖	`apt-get install`	WebKit2GTK、AppIndicator、librsvg 等
macOS 交叉编译	环境变量配置	`PKG_CONFIG_ALLOW_CROSS=1`，通过 `xcrun` 定位 SDK

Linux 编译依赖

CI 中 Linux 构建需要安装以下系统库（Source: .github/workflows/release.yml:86-87）：

sudo apt-get update
sudo apt-get install -y \
    libwebkit2gtk-4.1-dev \
    libappindicator3-dev \
    librsvg2-dev

macOS 交叉编译配置

macOS 在同一 Runner 上同时构建 arm64 和 x86_64 两个目标。通过环境变量控制交叉编译行为（Source: .github/workflows/release.yml:95-100）：

# 允许交叉编译时的 pkg-config 查找
export PKG_CONFIG_ALLOW_CROSS=1

# 通过 xcrun 定位 macOS SDK 路径
export SDK_PATH="$(xcrun --show-sdk-path)"

CI 编译环境架构

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["GitHub Actions<br/>触发 Release 构建"] --> B["检出代码<br/>actions/checkout"]
    B --> C["安装 Node.js<br/>actions/setup-node@v4"]
    C --> D["安装 Rust 工具链<br/>dtolnay/rust-toolchain@stable"]
    D --> E{"目标平台?"}

    E -- "Linux<br/>ubuntu-22.04" --> F1["安装系统依赖<br/>libwebkit2gtk-4.1-dev<br/>libappindicator3-dev<br/>librsvg2-dev"]
    F1 --> G1["npm ci && npm run tauri build<br/>x86_64-unknown-linux-gnu"]

    E -- "macOS<br/>macos-latest" --> F2["配置交叉编译环境<br/>PKG_CONFIG_ALLOW_CROSS=1<br/>SDK_PATH via xcrun"]
    F2 --> G2["npm ci && npm run tauri build<br/>aarch64-apple-darwin"]
    F2 --> G3["npm ci && npm run tauri build<br/>x86_64-apple-darwin"]

    E -- "Windows<br/>windows-latest" --> F3["使用预装 MSVC 工具链"]
    F3 --> G4["npm ci && npm run tauri build<br/>x86_64-pc-windows-msvc"]

    G1 --> H["上传构建产物"]
    G2 --> H
    G3 --> H
    G4 --> H

    style A fill:#3498db,stroke:#2980b9,color:#fff
    style H fill:#2ecc71,stroke:#27ae60,color:#fff
    style F1 fill:#e95420,stroke:#c7372d,color:#fff
    style F2 fill:#555555,stroke:#333333,color:#fff
    style F3 fill:#0078d4,stroke:#005a9e,color:#fff

快速开始

1. 克隆仓库

git clone https://github.com/zephyr-project/zephyr.git
cd zephyr

2. 安装前端依赖

npm install

3. 开发模式运行

# 启动开发模式（前端热更新 + Rust 后端）
npm run tauri dev

首次运行时，Cargo 会下载并编译所有 Rust 依赖，可能需要 5-15 分钟（取决于网络和硬件）。后续启动会快很多。

4. 生产构建

# 构建生产版本
npm run tauri build

构建产物位于 apps/desktop/src-tauri/target/release/bundle/ 目录下：

平台	路径	格式
Windows	`apps/desktop/src-tauri/target/release/bundle/msi/`	.msi
Windows	`apps/desktop/src-tauri/target/release/bundle/nsis/`	.exe
macOS	`apps/desktop/src-tauri/target/release/bundle/dmg/`	.dmg
macOS	`apps/desktop/src-tauri/target/release/bundle/macos/`	.app
Linux	`apps/desktop/src-tauri/target/release/bundle/deb/`	.deb
Linux	`apps/desktop/src-tauri/target/release/bundle/rpm/`	.rpm
Linux	`apps/desktop/src-tauri/target/release/bundle/appimage/`	.AppImage

多平台构建矩阵

下图展示了 Tauri 构建命令如何并行生成各平台的安装包：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}}}%%
graph TB
    BUILD["GitHub Actions<br/>Release 工作流"] --> MAC_ARM["macOS arm64<br/>aarch64-apple-darwin<br/>Runner: macos-latest"]
    BUILD --> MAC_X64["macOS x64<br/>x86_64-apple-darwin<br/>Runner: macos-latest"]
    BUILD --> LNX_X64["Linux x64<br/>x86_64-unknown-linux-gnu<br/>Runner: ubuntu-22.04"]
    BUILD --> WIN_X64["Windows x64<br/>x86_64-pc-windows-msvc<br/>Runner: windows-latest"]

    subgraph macOS["macOS 平台 (macos-latest)"]
        DMG["DMG 镜像<br/>.dmg"]
        APP[".app 应用包"]
    end

    subgraph Linux["Linux 平台 (ubuntu-22.04)"]
        DEB["DEB 包<br/>Ubuntu/Debian"]
        RPM["RPM 包<br/>Fedora/RHEL"]
        AIMG["AppImage<br/>通用格式"]
    end

    subgraph Windows["Windows 平台 (windows-latest)"]
        NSIS["NSIS 安装包<br/>.exe"]
        MSI["MSI 安装包<br/>.msi"]
    end

    MAC_ARM --> DMG
    MAC_ARM --> APP
    MAC_X64 --> DMG
    MAC_X64 --> APP
    LNX_X64 --> DEB
    LNX_X64 --> RPM
    LNX_X64 --> AIMG
    WIN_X64 --> NSIS
    WIN_X64 --> MSI

    style BUILD fill:#3498db,stroke:#2980b9,color:#fff
    style macOS fill:#555555,stroke:#333333,color:#fff
    style Linux fill:#e95420,stroke:#c7372d,color:#fff
    style Windows fill:#0078d4,stroke:#005a9e,color:#fff

Tauri 构建打包流程

下图展示了从构建命令到最终安装包输出的完整打包流程：

%%{init: {'themeVariables': {'fontSize': '9px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '8px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 12, 'rankSpacing': 15}}}%%
flowchart TD
    A["npm run tauri build"] --> B["Tailwind CSS 编译<br/>(styles.css → tailwind.css)"]
    B --> C["Cargo 编译 Rust 后端<br/>(release mode)"]
    C --> D{"平台?"}

    D -- "Windows" --> E1["NSIS 打包<br/>(.exe)"]
    D -- "Windows" --> E2["MSI 打包<br/>(.msi)"]

    D -- "macOS" --> F1["codesign 签名"]
    F1 --> F2["create-dmg 打包<br/>(.dmg)"]
    F2 --> F3["notarize 公证"]

    D -- "Linux" --> G1["cargo-bundle"]
    G1 --> G2["DEB 打包"]
    G1 --> G3["RPM 打包"]
    G1 --> G4["AppImage 打包"]

    E1 --> H["输出到<br/>target/release/bundle/"]
    E2 --> H
    F3 --> H
    G2 --> H
    G3 --> H
    G4 --> H

    style A fill:#3498db,stroke:#2980b9,color:#fff
    style H fill:#2ecc71,stroke:#27ae60,color:#fff
    style E1 fill:#0078d4,stroke:#005a9e,color:#fff
    style E2 fill:#0078d4,stroke:#005a9e,color:#fff
    style F1 fill:#555555,stroke:#333333,color:#fff
    style F2 fill:#555555,stroke:#333333,color:#fff
    style F3 fill:#555555,stroke:#333333,color:#fff
    style G2 fill:#e95420,stroke:#c7372d,color:#fff
    style G3 fill:#e95420,stroke:#c7372d,color:#fff
    style G4 fill:#e95420,stroke:#c7372d,color:#fff

Geo-Data 获取流程

在 CI 构建过程中，Full 版本需要下载 GeoIP 和 GeoSite 数据文件，用于 Mihomo 内核的路由规则匹配（Source: .github/workflows/release.yml:249-255）：

%%{init: {'themeVariables': {'fontSize': '10px', 'nodeBorder': '1px', 'clusterBorder': '1px', 'edgeLabelHeight': '10px'}, 'flowchart': {'curve': 'basis', 'nodeSpacing': 15, 'rankSpacing': 25}}}%%
flowchart LR
    A["CI 构建触发"] --> B["下载 geoip.dat<br/>GeoIP 数据库"]
    A --> C["下载 geosite.dat<br/>GeoSite 规则集"]
    B --> D["放置到<br/>apps/desktop/src-tauri/bundled/"]
    C --> D
    D --> E["打包进 Full 版本"]

    style A fill:#3498db,stroke:#2980b9,color:#fff
    style D fill:#f39c12,stroke:#e67e22,color:#fff
    style E fill:#2ecc71,stroke:#27ae60,color:#fff

文件	说明	放置路径
`geoip.dat`	GeoIP 数据库，用于 IP 地理位置判断	`apps/desktop/src-tauri/bundled/geoip.dat`
`geosite.dat`	GeoSite 规则集，用于域名分类匹配	`apps/desktop/src-tauri/bundled/geosite.dat`

注意：Geo-Data 文件仅包含在 Full 版本中，Lite 版本不包含这些数据文件。

npm scripts 说明

项目 package.json 中定义了以下脚本命令：

命令	说明	用途
`npm run build:css`	使用 Tailwind CSS CLI 编译样式	将 `apps/desktop/src/styles.css` 编译为 `apps/desktop/src/tailwind.css`
`npm run dev:css`	Tailwind CSS watch 模式	开发时实时编译样式
`npm run lint`	运行 ESLint 检查	前端代码质量检查
`npm run test`	运行 Vitest 单元测试	前端测试
`npm run tauri`	运行 Tauri CLI 命令	Tauri 通用命令入口（`dev`、`build` 等作为参数传入）

Tauri CLI 常用命令

# 开发模式
npm run tauri dev

# 生产构建
npm run tauri build

# 仅构建 Rust 部分（调试）
npm run tauri build -- --debug

# 查看应用信息
npm run tauri info

# 升级 Tauri 依赖
npm run tauri dev -- --updater

代码质量工具

Zephyr 使用多层代码质量工具确保代码质量和安全性：

前端工具

ESLint

前端代码静态分析工具，配置文件为 eslint.config.js（Source: eslint.config.js:1-44）：

# 检查代码
npm run lint

配置详情：

目标文件：*.js（JavaScript 文件）
忽略路径：构建产物目录及 apps/desktop/src-tauri/
浏览器全局变量（只读）：window、document、fetch、WebSocket、localStorage
自定义全局变量：jsyaml

核心规则：

规则	级别	说明
`no-unused-vars`	`"off"`	允许未使用变量
`no-undef`	`"error"`	禁止使用未定义变量

Vitest

单元测试框架：

# 运行所有测试
npm run test

后端工具

Clippy

Rust 代码检查工具，配置了 12 条严格规则（详见 Contributing.md）：

# 运行 Clippy 检查
cd src-tauri
cargo clippy -- -D warnings

# 自动修复部分问题
cargo clippy --fix

rustfmt

Rust 代码格式化工具：

# 检查格式
cargo fmt --check

# 格式化代码
cargo fmt

cargo-deny

依赖审计和许可证检查工具：

# 检查许可证合规性
cd src-tauri
cargo deny check licenses

# 检查依赖安全
cargo deny check bans

# 检查所有
cargo deny check

cargo-audit

Rust 安全漏洞扫描：

# 扫描已知漏洞
cargo audit

安全工具

Semgrep

跨语言静态安全分析工具：

# 运行自定义规则
semgrep --config .semgrep.yml apps/desktop/src/ apps/desktop/src-tauri/

# 运行默认规则集
semgrep --config auto src/

CodeQL

GitHub 原生的语义代码分析，在 CI 中自动运行。

常见构建问题

Q: cargo build 报错 "linker 'link.exe' not found" (Windows)

A: 需要安装 Visual Studio Build Tools：

下载 Visual Studio Build Tools
安装时勾选"C++ 桌面开发"工作负载
确保安装了 Windows SDK
重新打开终端后重试

Q: 编译时提示 "webkit2gtk not found" (Linux)

A: 需要安装 WebKit2GTK 开发包：

# Ubuntu / Debian
sudo apt install libwebkit2gtk-4.1-dev

# Fedora
sudo dnf install webkit2gtk4.1-devel

# Arch Linux
sudo pacman -S webkit2gtk-4.1

Q: 首次编译时间过长

A: 首次编译需要下载和编译所有 Rust 依赖（约 200+ 个 crate），通常需要 5-15 分钟。后续增量编译会快很多。你可以：

使用 sccache 加速编译：

cargo install sccache
export RUSTC_WRAPPER=sccache

确保网络通畅，Cargo 需要从 crates.io 下载依赖
如果使用代理，配置 Cargo 代理设置

Q: 如何配置 Cargo 镜像源加速下载？

A: 在 ~/.cargo/config.toml 中添加：

[source.crates-io]
replace-with = 'ustc'

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"

Q: macOS 构建时签名错误

A: 如果没有 Apple Developer 账号，可以在 apps/desktop/src-tauri/tauri.conf.json 中禁用签名：

{
  "bundle": {
    "macOS": {
      "signingIdentity": "-"
    }
  }
}

注意：禁用签名后生成的 .app 无法通过公证，其他用户打开时会看到安全警告。

Q: 如何交叉编译？

A: Tauri 支持通过 GitHub Actions 进行跨平台构建。本地交叉编译较为复杂，建议使用 CI/CD：

推送代码到 GitHub
创建 Release Tag 触发构建
CI 会自动构建所有平台版本

如需本地交叉编译，请参考 Tauri 交叉编译文档。

构建完成后，建议阅读 Contributing.md 了解代码规范和提交流程。

导航

外部链接

Uh oh!

BuildGuide

构建指南

目录

项目结构

目录说明

开发工作流

环境要求

通用依赖

安装 Rust 工具链

安装 Node.js

平台特定依赖

Windows

macOS

Linux

编译环境

工具链配置

Linux 编译依赖

macOS 交叉编译配置

CI 编译环境架构

快速开始

1. 克隆仓库

2. 安装前端依赖

3. 开发模式运行

4. 生产构建

多平台构建矩阵

Tauri 构建打包流程

Geo-Data 获取流程

npm scripts 说明

Tauri CLI 常用命令

代码质量工具

前端工具

ESLint

Vitest

后端工具

Clippy

rustfmt

cargo-deny

cargo-audit

安全工具

Semgrep

CodeQL

常见构建问题

Q: cargo build 报错 "linker 'link.exe' not found" (Windows)

Q: 编译时提示 "webkit2gtk not found" (Linux)

Q: 首次编译时间过长

Q: 如何配置 Cargo 镜像源加速下载？

Q: macOS 构建时签名错误

Q: 如何交叉编译？

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally