Rust
d02eed3bd8
- 添加完整的 GitHub Actions 构建指南文档 - BUILD_GUIDE.md: Android 详细构建指南 - MULTIPLATFORM_GUIDE.md: 多平台构建指南 - HOW_TO_BUILD.md: 分步操作教程 - QUICKSTART.md: 3步快速开始指南 - INDEX.md: 文档总览索引 - README.md: 基础说明 - 创建 docs/ 目录存放项目文档 - 锁定 libcore 子模块到 f993a57 (v3.1.7) - 防止在线编译时使用最新版本 - 确保构建稳定性和一致性
346 lines
6.5 KiB
Markdown
346 lines
6.5 KiB
Markdown
# Clash Meta 核心编译指南
|
|
|
|
## 环境准备
|
|
|
|
### 1. 安装必要工具
|
|
|
|
```bash
|
|
# macOS
|
|
brew install go
|
|
brew install android-ndk # 或从 Android Studio 安装
|
|
|
|
# 验证
|
|
go version # 需要 go 1.20+
|
|
```
|
|
|
|
### 2. 配置环境变量
|
|
|
|
```bash
|
|
# 添加到 ~/.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: 使用项目脚本 (推荐)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 \
|
|
.
|
|
```
|
|
|
|
## 编译优化
|
|
|
|
### 减小文件体积
|
|
|
|
```bash
|
|
# 使用 -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 压缩 (可选)
|
|
|
|
```bash
|
|
# 安装 UPX
|
|
brew install upx
|
|
|
|
# 压缩 SO 文件 (可减少 30-50% 体积)
|
|
upx --best --lzma libclash.so
|
|
|
|
# ⚠️ 注意: UPX 压缩可能导致某些设备加载失败,仅在测试环境使用
|
|
```
|
|
|
|
## 常见问题
|
|
|
|
### 问题 1: `undefined reference to 'xxx'`
|
|
|
|
**原因:** NDK 版本不匹配或缺少依赖
|
|
|
|
**解决:**
|
|
```bash
|
|
# 检查 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 环境变量路径错误
|
|
|
|
**解决:**
|
|
```bash
|
|
# 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)
|
|
|
|
**原因:** 未启用优化参数
|
|
|
|
**解决:**
|
|
```bash
|
|
# 确保使用 -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`
|
|
|
|
**原因:** 子模块未初始化
|
|
|
|
**解决:**
|
|
```bash
|
|
cd core
|
|
git submodule update --init --recursive
|
|
go mod download
|
|
```
|
|
|
|
## 验证编译结果
|
|
|
|
### 1. 检查导出函数
|
|
|
|
```bash
|
|
nm -D libclash.so | grep -E "(quickStart|getAndroidVpnOptions|startTUN)"
|
|
|
|
# 预期输出:
|
|
# 0000000000e23960 T getAndroidVpnOptions
|
|
# 0000000000e237b0 T quickStart
|
|
# 0000000000e23820 T startTUN
|
|
```
|
|
|
|
### 2. 检查架构
|
|
|
|
```bash
|
|
file libclash.so
|
|
|
|
# ARM64 预期输出:
|
|
# libclash.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked
|
|
```
|
|
|
|
### 3. 测试加载
|
|
|
|
```bash
|
|
# 在 Android 设备上测试
|
|
adb push libclash.so /data/local/tmp/
|
|
adb shell "cd /data/local/tmp && LD_LIBRARY_PATH=. /system/bin/true" # 测试加载
|
|
```
|
|
|
|
## 持续集成 (CI/CD)
|
|
|
|
### GitHub Actions 示例
|
|
|
|
```yaml
|
|
# .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 子模块
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
### 查看版本信息
|
|
|
|
```bash
|
|
# 查看当前 Clash.Meta 版本
|
|
cd core/Clash.Meta
|
|
git log -1 --oneline
|
|
|
|
# 查看依赖版本
|
|
cd ..
|
|
go list -m github.com/metacubex/mihomo
|
|
```
|
|
|
|
## 调试编译问题
|
|
|
|
### 启用详细日志
|
|
|
|
```bash
|
|
# 查看详细编译过程
|
|
go build -v -x -buildmode=c-shared -o libclash.so .
|
|
|
|
# -v: 显示正在编译的包
|
|
# -x: 显示执行的命令
|
|
```
|
|
|
|
### 检查依赖
|
|
|
|
```bash
|
|
# 列出所有依赖
|
|
go list -m all
|
|
|
|
# 检查特定依赖
|
|
go mod why github.com/metacubex/mihomo
|
|
```
|
|
|
|
## 性能优化
|
|
|
|
### 编译时优化
|
|
|
|
```bash
|
|
# 启用所有优化
|
|
go build -buildmode=c-shared \
|
|
-ldflags="-s -w -extldflags=-Wl,-z,now" \
|
|
-trimpath \
|
|
-tags="with_gvisor,with_quic" \
|
|
-o libclash.so \
|
|
.
|
|
```
|
|
|
|
### Profile 引导优化 (PGO)
|
|
|
|
```bash
|
|
# 1. 生成性能剖析文件
|
|
go test -cpuprofile=cpu.prof ./...
|
|
|
|
# 2. 使用剖析文件编译
|
|
go build -buildmode=c-shared \
|
|
-pgo=cpu.prof \
|
|
-o libclash.so \
|
|
.
|
|
```
|
|
|
|
## 相关资源
|
|
|
|
- [Android NDK 官方文档](https://developer.android.com/ndk)
|
|
- [Go 交叉编译指南](https://go.dev/doc/install/source#environment)
|
|
- [Clash Meta 编译指南](https://wiki.metacubex.one/dev/)
|