hi-client/docs/CLASH_BUILD_GUIDE.md

Clash Meta 核心编译指南

环境准备

1. 安装必要工具

# macOS
brew install go
brew install android-ndk  # 或从 Android Studio 安装

# 验证
go version  # 需要 go 1.20+

2. 配置环境变量

# 添加到 ~/.zshrc 或 ~/.bash_profile
export ANDROID_HOME="$HOME/Library/Android/sdk"
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/29.0.14033849"  # 根据实际版本调整
export PATH="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin:$PATH"

# 应用配置
source ~/.zshrc

编译步骤

方法 1: 使用项目脚本 (推荐)

cd /Users/mac/Project/Dart/LighthouseApp/core

# 编译 ARM64 版本
make android-arm64

# 编译所有架构
make android-all  # arm64-v8a, armeabi-v7a, x86, x86_64

方法 2: 手动编译

编译 ARM64 (arm64-v8a)

cd /Users/mac/Project/Dart/LighthouseApp/core

# 1. 初始化 Go 模块
go mod download
git submodule update --init --recursive

# 2. 设置交叉编译环境
export CGO_ENABLED=1
export GOOS=android
export GOARCH=arm64
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android29-clang"

# 3. 编译为共享库
go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o ../android/app/src/main/jniLibs/arm64-v8a/libclash.so \
  .

# 4. 验证编译结果
ls -lh ../android/app/src/main/jniLibs/arm64-v8a/libclash.so
nm -D ../android/app/src/main/jniLibs/arm64-v8a/libclash.so | grep quickStart

编译 ARMv7 (armeabi-v7a)

export GOARCH=arm
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi29-clang"

go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o ../android/app/src/main/jniLibs/armeabi-v7a/libclash.so \
  .

编译 x86_64

export GOARCH=amd64
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/x86_64-linux-android29-clang"

go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o ../android/app/src/main/jniLibs/x86_64/libclash.so \
  .

编译优化

减小文件体积

# 使用 -ldflags 优化
go build -buildmode=c-shared \
  -ldflags="-s -w -X 'github.com/metacubex/mihomo/constant.Version=1.0.0'" \
  -trimpath \
  -o libclash.so \
  .

# -s: 去除符号表
# -w: 去除 DWARF 调试信息
# -trimpath: 移除文件系统路径

UPX 压缩 (可选)

# 安装 UPX
brew install upx

# 压缩 SO 文件 (可减少 30-50% 体积)
upx --best --lzma libclash.so

# ⚠️ 注意: UPX 压缩可能导致某些设备加载失败,仅在测试环境使用

常见问题

问题 1: undefined reference to 'xxx'

原因: NDK 版本不匹配或缺少依赖

解决:

# 检查 NDK 版本
ls $ANDROID_HOME/ndk/

# 使用推荐版本 (r25c / 25.2.9519653 或更高)
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/25.2.9519653"

问题 2: clang: command not found

原因: CC 环境变量路径错误

解决:

# macOS (Apple Silicon)
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-aarch64/bin/aarch64-linux-android29-clang"

# macOS (Intel)
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android29-clang"

问题 3: 编译后文件过大 (>50MB)

原因: 未启用优化参数

解决:

# 确保使用 -ldflags="-s -w"
go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o libclash.so \
  .

# 预期大小: 25-30MB (ARM64)

问题 4: go: github.com/metacubex/mihomo: module not found

原因: 子模块未初始化

解决:

cd core
git submodule update --init --recursive
go mod download

验证编译结果

1. 检查导出函数

nm -D libclash.so | grep -E "(quickStart|getAndroidVpnOptions|startTUN)"

# 预期输出:
# 0000000000e23960 T getAndroidVpnOptions
# 0000000000e237b0 T quickStart
# 0000000000e23820 T startTUN

2. 检查架构

file libclash.so

# ARM64 预期输出:
# libclash.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked

3. 测试加载

# 在 Android 设备上测试
adb push libclash.so /data/local/tmp/
adb shell "cd /data/local/tmp && LD_LIBRARY_PATH=. /system/bin/true"  # 测试加载

持续集成 (CI/CD)

GitHub Actions 示例

# .github/workflows/build-clash-core.yml
name: Build Clash Core

on:
  push:
    paths:
      - 'core/**'
  workflow_dispatch:

jobs:
  build-android:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        arch: [arm64, arm, amd64]

    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - uses: actions/setup-go@v4
        with:
          go-version: '1.20'

      - name: Setup Android NDK
        uses: nttld/setup-ndk@v1
        with:
          ndk-version: r25c

      - name: Build
        run: |
          cd core
          make android-${{ matrix.arch }}

      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: libclash-${{ matrix.arch }}
          path: android/app/src/main/jniLibs/**/libclash.so

更新核心版本

更新 Clash.Meta 子模块

cd core/Clash.Meta

# 更新到最新版本
git fetch origin
git checkout Alpha  # 或其他分支
git pull

cd ..
git add Clash.Meta
git commit -m "chore: update Clash.Meta to latest"

# 重新编译
make clean
make android-arm64

查看版本信息

# 查看当前 Clash.Meta 版本
cd core/Clash.Meta
git log -1 --oneline

# 查看依赖版本
cd ..
go list -m github.com/metacubex/mihomo

调试编译问题

启用详细日志

# 查看详细编译过程
go build -v -x -buildmode=c-shared -o libclash.so .

# -v: 显示正在编译的包
# -x: 显示执行的命令

检查依赖

# 列出所有依赖
go list -m all

# 检查特定依赖
go mod why github.com/metacubex/mihomo

性能优化

编译时优化

# 启用所有优化
go build -buildmode=c-shared \
  -ldflags="-s -w -extldflags=-Wl,-z,now" \
  -trimpath \
  -tags="with_gvisor,with_quic" \
  -o libclash.so \
  .

Profile 引导优化 (PGO)

# 1. 生成性能剖析文件
go test -cpuprofile=cpu.prof ./...

# 2. 使用剖析文件编译
go build -buildmode=c-shared \
  -pgo=cpu.prof \
  -o libclash.so \
  .

相关资源

• Android NDK 官方文档
• Go 交叉编译指南
• Clash Meta 编译指南