Clash Party Linux 版本编译指南（解决 Ubuntu-20.04 原生模块缺失问题）

问题描述

在 WSL Ubuntu 20.04 环境下编译并运行 Clash Party 时，出现以下错误：

Native binding not found: sysproxy.linux-x64-gnu.node

问题根源

上游依赖问题：关键的原生模块项目 mihomo-party-org/sysproxy-rs-opti在其 GitHub Releases 中只提供了针对 musl库的 Linux 预编译版本。
系统不兼容：Ubuntu 20.04 及大多数主流桌面 Linux 发行版使用的是 glibc（此处为 GLIBC 2.31），而 musl与 glibc并不兼容，直接使用会导致 libc 链接错误。
结果：因此，Clash Party 官方提供的资源包中缺少适用于 Ubuntu 20.04 的 sysproxy.linux-x64-gnu.node文件，导致应用启动失败。

解决方案概述

核心思路是从源码编译 sysproxy-rs-opti项目，生成适用于 glibc环境的 sysproxy.linux-x64-gnu.node文件，随后再完整编译 Clash Party 项目。

第一部分：基础环境搭建

1.1 安装系统构建依赖

打开终端，执行以下命令安装必要的编译工具和库。

 更新软件包列表
sudo apt update

 安装编译工具链和基础依赖
sudo apt install -y build-essential pkg-config libssl-dev

 (可选) 如需构建 RPM 格式安装包，可安装 rpm 工具
sudo apt install rpm

1.2 安装 Node.js 与 pnpm

确保已安装 Node.js。如果尚未安装，请参考 Node.js 官方文档或使用 Node 版本管理器（如 nvm）进行安装。

 全局安装 pnpm 包管理器
npm install -g pnpm

 验证安装
node --version
pnpm --version

1.3 安装 Rust 工具链

Rust 是编译原生模块 sysproxy-rs-opti所必需的。

 通过 rustup 安装 Rust (安装过程中按回车选择默认选项即可)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

 加载 Cargo (Rust 的包管理器) 环境变量
source $HOME/.cargo/env

 验证安装
rustc --version
cargo --version
 应显示 rustc 1.93.1 或更高版本

提示：可将 source $HOME/.cargo/env添加到 ~/.bashrc或 ~/.zshrc中，使 Rust 环境变量永久生效。

1.4 准备 Clash Party 项目源码

 进入您的项目目录（请根据实际情况调整路径）
cd /home/usr/clash-party

 安装项目的 Node.js 依赖
pnpm install

 运行准备脚本（此步骤会尝试下载资源，其中 sysproxy.linux-x64-gnu.node 会失败，这是正常的）
pnpm run prepare

第二部分：编译缺失的原生模块

2.1 获取 sysproxy-rs-opti 源码

 克隆仓库到临时目录
cd /tmp
git clone https://github.com/mihomo-party-org/sysproxy-rs-opti.git
cd sysproxy-rs-opti

 切换到与 clash-party 项目兼容的版本（至关重要！）
 版本号需查阅 `/home/usr/clash-party/scripts/prepare.mjs` 文件确认，例如 v0.1.0
git checkout v0.1.0

2.2 安装依赖并进行编译

使用 napi-rs工具链编译适用于 glibc的原生模块。

 安装项目所需的 npm 依赖
pnpm install

 编译针对 x86_64 GNU/Linux (glibc) 系统的发布版本
pnpm exec napi build --platform --release --target x86_64-unknown-linux-gnu

编译目标说明：

x86_64-unknown-linux-gnu：适用于 Ubuntu、Debian、Fedora 等使用 glibc的系统。
x86_64-unknown-linux-musl：适用于 Alpine Linux 等使用 musl的系统。

2.3 验证编译产物

编译成功后，当前目录下会生成 sysproxy.linux-x64-gnu.node文件（大小约为 964KB）。

 查看生成的文件
ls -lh sysproxy.linux-x64-gnu.node

 检查其动态库依赖，确认链接的是 glibc
ldd sysproxy.linux-x64-gnu.node

正常输出应包含 linux-vdso.so.1、libc.so.6(glibc)、libpthread.so.0等库。

2.4 将模块文件复制到 Clash Party 项目

 复制编译好的模块到 Clash Party 的指定目录
cp sysproxy.linux-x64-gnu.node /home/usr/clash-party/extra/sidecar/

 确保其具有可执行权限
chmod +x /home/usr/clash-party/extra/sidecar/sysproxy.linux-x64-gnu.node

 确认复制成功
ls -l /home/usr/clash-party/extra/sidecar/sysproxy.linux-x64-gnu.node

第三部分：编译 Clash Party 应用

3.1 开发模式测试

在正式打包前，建议先以开发模式运行，验证问题是否已解决。

cd /home/usr/clash-party
pnpm dev

如果应用能够正常启动且控制台不再出现 ”Native binding not found”错误，则表明原生模块已成功加载。

3.2 构建 Linux 安装包

使用以下命令进行正式构建。

 构建适用于 Debian/Ubuntu 的 .deb 安装包
pnpm run build:linux

构建成功后，安装包将生成在 dist/目录下，例如：

dist/clash-party-linux-1.9.1-amd64.deb(Debian/Ubuntu)
(如果安装了rpm工具) dist/clash-party-linux-1.9.1-x86_64.rpm(Fedora/RHEL)

3.3 安装与运行（可选）

 安装 .deb 包
sudo dpkg -i /home/usr/clash-party/dist/clash-party-linux-*.deb

 如果安装过程中提示依赖问题，运行以下命令修复
sudo apt -f install

 启动应用程序
clash-party

注意事项

版本一致性：务必确保从源码编译的 sysproxy-rs-opti版本号与 Clash Party 项目 scripts/prepare.mjs中指定的版本完全一致。
平台区分：本指南编译的 gnu版本模块仅适用于基于 glibc的 Linux 系统（如 Ubuntu、Debian、CentOS 等）。若需在 Alpine Linux (musl) 上运行，应编译 musl目标。
清理缓存：如果之前因下载失败残留了错误的小文件（如9字节的无效.node文件），请在复制新文件前将其删除：
```
rm -f /home/usr/clash-party/extra/sidecar/sysproxy.linux-x64-gnu.node
```

故障排查

问题现象：Command ‘napi’ not found

可能原因：napi命令未在全局安装，需通过 pnpm调用。
解决方案：使用 pnpm exec napi build ...而非直接运行 napi。

问题现象：build-essential not installed

可能原因：缺少基础的编译工具包。
解决方案：运行 sudo apt install build-essential。

问题现象：运行时报 libc.so相关错误

可能原因：错误地使用了 musl版本的模块。
解决方案：严格按照本指南从源码编译 gnu版本模块。

问题现象：pnpm install网络超时或缓慢

可能原因：网络连接问题。
解决方案：配置国内 npm 镜像源：pnpm config set registry https://registry.npmmirror.com

问题现象：Rust 编译报错 linker not found

可能原因：缺少 C 语言链接器。
解决方案：确保已安装 build-essential：sudo apt install build-essential。

项目结构参考

成功编译后，您的 Clash Party 项目关键目录结构应如下所示：

/home/usr/clash-party/
├── extra/
│   └── sidecar/
│       ├── sysproxy.linux-x64-gnu.node  本指南核心产出，手动编译的 glibc 模块
│       ├── mihomo                       Mihomo 核心
│       ├── mihomo-alpha
│       └── mihomo-smart
├── src/
│   └── native/
│       └── sysproxy/
│           └── index.js                 加载原生模块的逻辑
├── scripts/
│   └── prepare.mjs                      资源下载脚本，可在此查版本号
└── dist/                                最终构建产物目录
    └── clash-party-linux-1.9.1-amd64.deb

附录：快速命令汇总

完整编译流程（一键式，适合全新环境）

 1. 安装系统与编译环境
sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
npm install -g pnpm

 2. 编译 sysproxy 原生模块
cd /tmp && \
git clone https://github.com/mihomo-party-org/sysproxy-rs-opti.git && \
cd sysproxy-rs-opti && \
git checkout v0.1.0 && \
pnpm install && \
pnpm exec napi build --platform --release --target x86_64-unknown-linux-gnu && \
cp sysproxy.linux-x64-gnu.node /home/usr/clash-party/extra/sidecar/

 3. 编译 Clash Party
cd /home/usr/clash-party && \
pnpm run build:linux

仅重新编译 sysproxy 模块（当 Clash Party 项目已就绪时）

cd /tmp/sysproxy-rs-opti
pnpm exec napi build --platform --release --target x86_64-unknown-linux-gnu
cp sysproxy.linux-x64-gnu.node /home/usr/clash-party/extra/sidecar/

仅重新打包 Clash Party（当原生模块已就绪时）

cd /home/usr/clash-party
pnpm run build:linux

参考链接：

WSL下编译Clash Party