Clash Verge 开发者文档

说明 Clash Verge 的图形界面负责呈现与交互，客户端通过 Tauri/Rust 与系统能力连接，并通过 Mihomo API 读取或修改内核运行状态。 遇到问题时，应先判断它属于前端界面、桌面应用层，还是 Mihomo 内核层。

注意 Linux 依赖名称会随发行版变化；当前贡献文档以 Ubuntu 为例列出 WebKitGTK、Ayatana AppIndicator、librsvg 与 patchelf。 Windows ARM 还需要 LLVM/clang。具体依赖始终以仓库最新 CONTRIBUTING.md 为准。

1. 克隆仓库

   拿到源码并进入项目目录。

2. 安装前端依赖

   仓库使用 pnpm 管理依赖，混用别的包管理器容易导致锁文件冲突。

3. 准备 Mihomo 与运行时资源

   执行项目的 prebuild 脚本，下载当前平台所需的 Mihomo 内核与 service/sidecar 资源。

4. 启动开发模式

   pnpm dev 用于标准开发流程；需要直接运行 Tauri 开发模式时也可使用仓库提供的 pnpm dev:tauri。

5. 打包安装包

   pnpm build 生成正式构建；需要更快的测试构建时可使用项目提供的 pnpm build:fast。

# 1. 克隆仓库
git clone https://github.com/clash-verge-rev/clash-verge-rev.git
cd clash-verge-rev

# 2. 启用包管理器并安装依赖
corepack enable
pnpm install

# 3. 下载 Mihomo 内核与运行时资源
pnpm run prebuild
# 需要重新下载时：
# pnpm run prebuild --force

# 4. 启动 Clash Verge 开发环境
pnpm dev
# 可选：pnpm dev:tauri

# 5. 构建当前平台
pnpm build
# 快速测试构建：pnpm build:fast

说明 当前仓库使用 pnpm 管理前端依赖，开发前应先执行 pnpm run prebuild 准备内核与服务资源。 命令名称和参数以后仍可能调整，因此应同时核对 package.json 与 CONTRIBUTING.md。

clash-verge-rev/
├─ src/                    # React + TypeScript 前端
├─ src-tauri/              # Tauri 2 + Rust 桌面应用层
│  ├─ src/                 # Rust 业务与系统集成代码
│  ├─ resources/           # 应用运行资源
│  ├─ sidecar/             # Mihomo 等外部二进制资源
│  ├─ Cargo.toml           # Rust 依赖
│  └─ tauri.conf.json      # Tauri 构建、应用标识与打包配置
├─ scripts/                # prebuild、版本与发布辅助脚本
├─ .github/                # CI / GitHub Actions
├─ package.json            # 前端依赖与 pnpm scripts
├─ CONTRIBUTING.md         # 官方贡献与开发环境说明
└─ UPDATELOG.md            # 版本更新记录

说明 目录结构会随开发分支调整，上表用于建立代码层级认知。实际修改前应直接查看当前仓库； 涉及界面文案时还应同步项目的国际化资源，并运行相应的格式与检查命令。

import { invoke } from "@tauri-apps/api/core";
import { listen } from "@tauri-apps/api/event";

// 调用 Rust 侧已经注册的 Tauri 命令
const result = await invoke("command_name", {
  payload: { key: "value" },
});

// 监听 Rust 侧事件
const unlisten = await listen("event-name", (event) => {
  console.log(event.payload);
});

// 页面或组件卸载时取消监听
unlisten();

// 示意：Rust 侧通过 #[tauri::command] 暴露命令
#[tauri::command]
fn command_name(payload: serde_json::Value) -> Result<serde_json::Value, String> {
    Ok(payload)
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![command_name])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

注意 上面的代码只说明 Tauri invoke / event 的通信模型，不代表 Clash Verge 当前实际命令名。 开发具体功能时，应从前端调用位置追踪到 src-tauri 中真实注册的命令和事件。

# 示例地址：请替换为 Clash Verge 当前实际的 external-controller
BASE=http://127.0.0.1:9090
AUTH="Authorization: Bearer 你的-secret"

# 读取 Mihomo 版本与当前配置
curl -H "$AUTH" "$BASE/version"
curl -H "$AUTH" "$BASE/configs"

# 修改运行模式：rule / global / direct
curl -X PATCH -H "$AUTH" -d '{"mode":"rule"}' "$BASE/configs"

# 查看代理与策略组
curl -H "$AUTH" "$BASE/proxies"

# 查看活动连接
curl -H "$AUTH" "$BASE/connections"

# 实时流量与日志可使用 GET / WebSocket
# ws://127.0.0.1:9090/traffic?token=你的-secret
# ws://127.0.0.1:9090/logs?level=info&token=你的-secret

注意 示例中的端口只是 Mihomo API 演示值，Clash Verge 实际运行端口应以当前配置为准。 external-controller 具有较高控制权限，开发调试时应优先监听本机，并为 API 设置可靠的 secret。

说明 当前 Tauri 配置中的应用标识可在 src-tauri/tauri.conf.json 查看，但实际数据路径仍可能因平台和构建渠道不同而变化。 调试时优先使用客户端提供的应用目录/日志目录入口定位文件，修改前先备份。

1. 先确认贡献范围

   较大的功能或行为修改先通过 Issue / Discussion 对齐问题与方案；修复已有明确问题时也应引用对应上下文。

2. Fork 并新建分支

   一个分支只做一件事，分支名能说明意图，例如 fix/tray-menu-crash。

3. 运行代码检查与本地验证

   前端运行 pnpm lint，Rust 侧运行 cargo clippy-all，并用 cargo fmt / pnpm format 保持格式一致。

4. 使用签名提交

   官方贡献说明要求提交进行签名验证；同时保持提交信息清晰，一条提交尽量对应一个独立改动点。

5. 提交 PR 并附验证说明

   PR 中写清系统环境、修改范围与验证结果；涉及界面变化时附截图，涉及行为变化时说明复现步骤与测试方式。

注意 项目采用 GPL-3.0，提交代码意味着以同样协议授权。涉及新增依赖时请在 PR 里说明必要性与协议兼容性。

说明 对外分发时应以项目 GitHub Releases 为正式发行来源；自行构建版本需要明确标识来源。 Mihomo 稳定/Alpha 内核切换是客户端内核选择能力，不等同于 Clash Verge 应用版本的发布渠道。