sansenhoshi/ts-mobile-go

Fork 0

Files

T

sansen ef1bf61f9f 首次推送

2026-07-20 19:01:03 +08:00

17 KiB

Raw Blame History

ts-mobile-go 构建指南（新手向）

本文档面向没有 Android 开发经验的同学，手把手教你从零把这个项目跑起来。

1. 项目是什么

这是一个 TeamSpeak 客户端的 Android 手机应用，架构分两层：

┌─────────────────────────────────────────────┐
│  Android 层（Kotlin + Jetpack Compose）       │
│  负责：界面显示、用户交互、状态管理             │
├─────────────────────────────────────────────┤
│  Go 层（gomobile 编译成 .aar 库）             │
│  负责：TeamSpeak 协议通信、加密、数据处理       │
└─────────────────────────────────────────────┘

关键概念：

Go — 一门编程语言，这里用来写 TeamSpeak 的底层通信逻辑
gomobile — Go 官方工具，能把 Go 代码编译成 Android 能用的库文件（.aar）
AAR — Android Archive，Android 的库文件格式，类似于 Windows 的 .dll
Gradle — Android 的构建工具，类似前端的 Webpack/Vite，负责编译、打包、生成 APK
APK — Android Package，安卓手机上安装的应用文件，类似 Windows 的 .exe
Kotlin — Android 官方推荐的编程语言（类似 Java，但更现代）
Jetpack Compose — Android 的现代 UI 框架（类似 React/Vue，用代码写界面）

2. 需要安装哪些软件

软件	用途	必须？
Go 1.26+	编译 Go 通信层代码	✅ 是
IntelliJ IDEA 或 Android Studio	打开项目、编写代码、运行应用	✅ 是
Android SDK	Android 开发工具包（IDEA/Android Studio 会自带）	✅ 是
JDK 17+	Java 运行环境，Gradle 构建需要	✅ 是
ADB	把 APK 安装到手机上（IDEA 自带）	手机调试需要

你大概率已经有了： 如果你电脑上已经装过 IntelliJ IDEA 或 Android Studio，JDK 和 Android SDK 应该已经自带了，只需要额外装一个 Go。

3. 安装步骤详解

3.1 安装 Go

打开 https://go.dev/dl/
下载 Windows 的 .msi 安装包（选 go1.26.x.windows-amd64.msi）
双击安装，全部默认下一步即可
安装完成后，关闭并重新打开 命令行（CMD 或 PowerShell），验证：
```
go version
# 应该输出类似：go version go1.26.0 windows/amd64
```

3.2 安装 gomobile

gomobile 是 Go 的官方工具，用来把 Go 代码编译成 Android 能用的 .aar 文件。

打开命令行（CMD 或 PowerShell），执行：

# 1. 安装 gomobile
go install golang.org/x/mobile/cmd/gomobile@latest

# 2. 初始化 gomobile（下载 Android 相关的工具链）
gomobile init

验证：

gomobile version
# 应该输出版本号，没有报错就说明成功了

如果 gomobile 命令找不到： 说明 Go 的 bin 目录没加到系统 PATH。默认路径是 C:\Users\你的用户名\go\bin，把它加到系统环境变量 PATH 里，然后重新打开命令行。

3.3 安装 IntelliJ IDEA 或 Android Studio

二选一：

IntelliJ IDEA（推荐，你可能已经有了）— 需要 Ultimate 版或安装 Android 插件
Android Studio（免费）— https://developer.android.com/studio

安装时确保勾选了以下组件：

✅ Android SDK
✅ Android SDK Platform（API 26 以上）
✅ Android SDK Build-Tools
✅ JDK 17+（通常会自动安装）

安装完成后，确认 Android SDK 路径：

IDEA: File → Settings → Languages & Frameworks → Android SDK
Android Studio: 自动配置

记下这个路径（类似 C:\Users\你的用户名\AppData\Local\Android\Sdk），后面可能用到。

3.4 设置环境变量

打开系统环境变量设置（Win + S 搜索"环境变量"）：

变量名	值	说明
`ANDROID_HOME`	`C:\Users\你的用户名\AppData\Local\Android\Sdk`	Android SDK 路径
`JAVA_HOME`	`C:\Program Files\JetBrains\IntelliJ IDEA xxx\jbr`	JDK 路径（IDEA 自带的 JBR 即可）

怎么找到 JAVA_HOME？ 如果你用的是 IntelliJ IDEA，它自带了一个 JDK（叫 JBR）。路径类似：C:\Program Files\JetBrains\IntelliJ IDEA 2024.3\jbr 在 IDEA 的 File → Project Structure → SDK 里可以看到具体路径。

把以下路径加到系统 PATH 变量中：

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\tools

4. 第一次构建（全流程）

4.1 理解构建流程

整个构建分两步：

第一步：Go 代码 → .aar 文件
  go/teamspeak/bridge.go  ──(gomobile编译)──>  android/app/libs/teamspeak.aar

第二步：Android 代码 + .aar → .apk 文件
  android/app/src/**/*.kt + teamspeak.aar  ──(Gradle构建)──>  app-debug.apk

必须先完成第一步，才能做第二步。 因为 Android 代码依赖 Go 编译出来的 .aar 文件。

4.2 一键构建（推荐）

项目根目录下有一个构建脚本，自动完成所有步骤：

Windows：

cd E:\MyProject\ts-mobile\ts-mobile-go
build.bat

Linux / macOS：

cd /path/to/ts-mobile-go
chmod +x build.sh
./build.sh

脚本会自动：

✅ 检查 Go、gomobile、Android SDK 是否已安装
✅ 下载 Go 依赖
✅ 编译 Go 代码为 .aar 文件
✅ 调用 Gradle 构建 APK

构建成功后，APK 文件在：

android/app/build/outputs/apk/debug/app-debug.apk

4.3 手动构建（了解原理）

如果你想了解每一步在做什么，可以手动执行：

第一步：编译 Go → AAR

# 进入 Go 目录
cd E:\MyProject\ts-mobile\ts-mobile-go\go

# 下载 Go 依赖（类似 npm install）
go mod tidy

# 编译为 AAR（这是关键命令）
set JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8
gomobile bind -target=android -androidapi=26 -ldflags="-linkmode=external -extldflags=-Wl,--hash-style=both" -o ../android/app/libs/teamspeak.aar ./teamspeak

命令解释：

gomobile bind — 把 Go 代码编译成 Android 库
-target=android — 目标平台是 Android（自动包含所有架构：arm64、arm、x86、x86_64）
-androidapi=26 — 最低支持 Android 8.0（API 26）
-ldflags="-linkmode=external -extldflags=-Wl,--hash-style=both" — 重要！ 两个关键标志：
- -linkmode=external — 使用外部链接器（NDK 的 clang），避免 Go 内置链接器与 Android 信号处理冲突导致 SIGSEGV 崩溃
- -extldflags=-Wl,--hash-style=both — 强制生成兼容 Android 的 ELF hash 格式
-o ../android/app/libs/teamspeak.aar — 输出文件路径
./teamspeak — 要编译的 Go 包路径

为什么要设置 JAVA_TOOL_OPTIONS？ gomobile 内部会调用 javac（Java 编译器）来生成 Java 接口代码。 Windows 下 javac 默认用 GBK 编码，但我们的 Go 源码注释里有中文，是 UTF-8 编码。不设置这个会导致编译报错"非法字符"。

第二步：构建 Android APK

# 进入 Android 目录
cd E:\MyProject\ts-mobile\ts-mobile-go\android

# 构建 debug 版本的 APK
gradlew.bat assembleDebug

构建成功后，APK 在 app\build\outputs\apk\debug\app-debug.apk。

4.4 安装到手机

方法 A：用 ADB 命令安装

手机开启 USB 调试：
- 进入手机 设置 → 关于手机
- 连续点击 版本号 7 次，会提示"你已进入开发者模式"
- 返回设置，进入 开发者选项
- 打开 USB 调试
用 USB 数据线连接手机到电脑
手机上弹出"允许 USB 调试"的提示，点允许

在命令行执行：

# 查看是否识别到手机
adb devices
# 应该显示类似：
# List of devices attached
# XXXXXXXX    device

# 安装 APK
adb install E:\MyProject\ts-mobile\ts-mobile-go\android\app\build\outputs\apk\debug\app-debug.apk

安装成功后，手机上找到 "ts-mobile-go" 应用，点击打开即可

方法 B：直接把 APK 传到手机

构建完成后，找到 app-debug.apk 文件
通过微信/QQ/邮件/数据线发送到手机
手机上点击 APK 文件，允许安装未知来源应用，完成安装

5. 在 IDEA 中打开和运行

5.1 打开项目

启动 IntelliJ IDEA
File → Open
选择 E:\MyProject\ts-mobile\ts-mobile-go\android\ 目录（注意是 android 子目录，不是根目录）
弹出提示框，点击 Trust Project
等待右下角进度条走完（Gradle Sync，首次可能需要 2-5 分钟下载依赖）

如果提示安装 Android 插件： 点击安装，然后重启 IDEA。

5.2 配置运行设备

使用模拟器（推荐新手）

在 IDEA 中：Tools → Device Manager（或工具栏上的手机图标）
点击 Create Virtual Device
选择一个手机型号（比如 Pixel 7），点 Next
选择系统镜像：选 API 34 或更高版本（需要先点击 Download 下载）
点 Next → Finish
在 Device Manager 中点击 ▶ 启动模拟器

使用真机

手机开启 USB 调试（见 4.4 节）
USB 连接电脑
IDEA 工具栏的设备下拉框中应该能看到你的手机

5.3 运行应用

确保 IDEA 工具栏的设备下拉框中选择了你的手机或模拟器
确保运行配置选择的是 app
点击绿色三角 ▶ 按钮（或按 Shift + F10）
IDEA 会自动编译并安装到设备上

注意： 首次运行前，必须先完成 Go → AAR 的编译（第 4.2 或 4.3 节）。 IDEA 只负责 Android 部分的构建，不会自动编译 Go 代码。

5.4 查看运行日志

在 IDEA 底部面板找到 Logcat 标签页，可以看到应用的运行日志，方便调试。

6. 日常开发流程

改了 Go 代码（`go/` 目录下的文件）

# 重新编译 AAR
cd E:\MyProject\ts-mobile\ts-mobile-go\go
set JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8
gomobile bind -target=android -androidapi=26 -ldflags="-linkmode=external -extldflags=-Wl,--hash-style=both" -o ../android/app/libs/teamspeak.aar ./teamspeak

然后在 IDEA 中重新运行应用（点 ▶）即可。IDEA 会自动检测到 .aar 文件变化并重新打包。

改了 Kotlin 代码（`android/` 目录下的文件）

直接在 IDEA 中点 ▶ 运行，IDEA 会自动增量编译。

常用 IDEA 快捷键

操作	快捷键
运行	`Shift + F10`
调试	`Shift + F9`
全局搜索	`Shift + Shift`
格式化代码	`Ctrl + Alt + L`
查看当前文件结构	`Ctrl + F12`

7. 常见问题排查

Q: Gradle Sync 失败，提示 "Unresolved reference: dependencyResolutionManagement"

原因： settings.gradle.kts 中的 API 名称写错了。

解决： 确认 android/settings.gradle.kts 第 9 行是：

dependencyResolutionManagement {  // ← 不是 dependencyResolution

Q: gomobile bind 报错 "missing golang.org/x/mobile dependency"

原因： Go 模块缺少 golang.org/x/mobile 依赖。

解决：

cd E:\MyProject\ts-mobile\ts-mobile-go\go
go get -tool golang.org/x/mobile/cmd/gobind
go mod tidy

Q: gomobile bind 报错 "unknown revision v0.0.0"

原因： go.mod 中的依赖版本号不存在。

解决： 确认 go/go.mod 中的版本号是有效的：

require github.com/honeybbq/teamspeak-go v0.2.0

而不是 v0.0.0。

Q: javac 报错 "非法字符" 或 "GBK 不可映射字符"

原因： Go 源码中的中文注释在 Windows 下被 javac 当作 GBK 编码处理。

解决： 在执行 gomobile 之前设置环境变量：

set JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8

Q: gomobile bind 报错 "math.MaxUint32 overflows int"

原因： 上游 teamspeak-go 库在 32 位目标平台上有整数溢出问题。

解决： 这个问题已经通过本地 patch 修复了（见 go/_patches/ 目录）。如果仍然遇到，可以只编译 64 位版本：

gomobile bind -target=android/arm64 ...

注意是 android/arm64，不是 android（后者会同时编译 32 位和 64 位）。

Q: adb devices 显示 "unauthorized"

原因： 手机上没有授权这台电脑的 USB 调试。

解决： 检查手机屏幕，应该有一个"允许 USB 调试"的弹窗，点击允许。如果没有弹窗，拔掉 USB 重新插入。

Q: 安装 APK 时提示 "安装包似乎已损坏"

原因： 可能是构建过程中出了问题，或者手机架构不匹配。

解决：

在 IDEA 中执行 Build → Clean Project，然后重新构建
确认手机是 64 位 ARM 架构（2018 年以后的手机基本都是）

Q: IDEA 提示 "SDK not found" 或 "JAVA_HOME not set"

解决：

File → Project Structure → SDKs，添加 Android SDK 路径
File → Project Structure → Project，设置 JDK 为 17 或更高
确认系统环境变量中 ANDROID_HOME 和 JAVA_HOME 已正确设置

Q: 应用安装后打开闪退，Logcat 显示 "dlopen failed: empty/missing DT_HASH/DT_GNU_HASH"

原因： Go 1.24+ 编译器生成的 .so 文件使用了 Android 链接器不认识的新 hash 格式（DT_SUNW_HASH）。Android 需要传统的 DT_HASH 或 DT_GNU_HASH 格式。

解决： 重新编译 AAR 时加上 -ldflags 标志（构建脚本已包含）：

cd E:\MyProject\ts-mobile\ts-mobile-go\go
set JAVA_TOOL_OPTIONS=-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8
gomobile bind -target=android -androidapi=26 -ldflags="-linkmode=external -extldflags=-Wl,--hash-style=both" -o ../android/app/libs/teamspeak.aar ./teamspeak

然后重新构建 APK 并安装。

Q: 应用启动后几秒闪退，Logcat 显示 "Fatal signal 11 (SIGSEGV), code 2 (SEGV_ACCERR)"

原因： Go 运行时的信号处理与 Android 内存保护机制冲突。Go 使用 SIGSEGV 做垃圾回收和协程调度，但 Android 的 SEGV_ACCERR 策略会阻止这种用法。

解决： 重新编译 AAR 时加上 -linkmode=external 标志（构建脚本已包含）：

gomobile bind ... -ldflags="-linkmode=external -extldflags=-Wl,--hash-style=both" ...

-linkmode=external 强制 Go 使用 NDK 的外部链接器，避免内置链接器的信号处理冲突。

Q: 应用安装后打开闪退（其他原因）

可能原因： Go 编译的 .aar 文件有问题，或者没有 .aar 文件。

排查：

确认 android/app/libs/teamspeak.aar 文件存在且大小不为 0
重新执行 Go 编译步骤
在 IDEA 的 Logcat 中查看崩溃日志
如果看到 UnsatisfiedLinkError，说明 .aar 中的 .so 文件架构不匹配或格式有问题

附录：项目目录结构说明

ts-mobile-go/
├── go/                              ← Go 源码（底层通信）
│   ├── go.mod                       ← Go 的依赖声明（类似 package.json）
│   ├── go.sum                       ← Go 的依赖锁文件（类似 package-lock.json）
│   └── teamspeak/
│       └── bridge.go                ← 核心：TeamSpeak 客户端桥接代码
│
├── android/                         ← Android 项目（IDEA 打开这个目录）
│   ├── build.gradle.kts             ← 根级构建配置（定义 Kotlin、AGP 版本）
│   ├── settings.gradle.kts          ← 项目设置（仓库地址、模块声明）
│   ├── gradle.properties            ← Gradle 参数（内存、编码等）
│   ├── gradle/wrapper/              ← Gradle 版本管理（自动下载指定版本的 Gradle）
│   └── app/
│       ├── build.gradle.kts         ← 应用级构建配置（依赖、SDK 版本、签名等）
│       ├── libs/
│       │   └── teamspeak.aar        ← ← ← Go 编译产物，放在这里！
│       ├── proguard-rules.pro       ← 代码混淆规则
│       └── src/main/
│           ├── AndroidManifest.xml  ← 应用声明（权限、入口 Activity 等）
│           └── java/com/tsmobile/app/
│               ├── MainActivity.kt      ← 应用入口
│               ├── TSBridge.kt          ← Kotlin 调用 Go 的桥接层
│               ├── ui/
│               │   ├── components/      ← 可复用 UI 组件
│               │   ├── screens/         ← 各页面（连接、频道、聊天等）
│               │   ├── navigation/      ← 页面路由
│               │   └── theme/           ← 主题颜色、字体
│               └── viewmodel/           ← 状态管理（ViewModel）
│
├── build.bat                        ← Windows 一键构建脚本
├── build.sh                         ← Linux/macOS 一键构建脚本
└── BUILD.md                         ← 本文件

17 KiB Raw Blame History Unescape Escape

ts-mobile-go 构建指南（新手向）

目录

1. 项目是什么

2. 需要安装哪些软件

3. 安装步骤详解

3.1 安装 Go

3.2 安装 gomobile

3.3 安装 IntelliJ IDEA 或 Android Studio

3.4 设置环境变量

4. 第一次构建（全流程）

4.1 理解构建流程

4.2 一键构建（推荐）

4.3 手动构建（了解原理）

4.4 安装到手机

方法 A：用 ADB 命令安装

方法 B：直接把 APK 传到手机

5. 在 IDEA 中打开和运行

5.1 打开项目

5.2 配置运行设备

使用模拟器（推荐新手）

使用真机

5.3 运行应用

5.4 查看运行日志

6. 日常开发流程

改了 Go 代码（go/ 目录下的文件）

改了 Kotlin 代码（android/ 目录下的文件）

常用 IDEA 快捷键

7. 常见问题排查

Q: Gradle Sync 失败，提示 "Unresolved reference: dependencyResolutionManagement"

Q: gomobile bind 报错 "missing golang.org/x/mobile dependency"

Q: gomobile bind 报错 "unknown revision v0.0.0"

Q: javac 报错 "非法字符" 或 "GBK 不可映射字符"

Q: gomobile bind 报错 "math.MaxUint32 overflows int"

Q: adb devices 显示 "unauthorized"

Q: 安装 APK 时提示 "安装包似乎已损坏"

Q: IDEA 提示 "SDK not found" 或 "JAVA_HOME not set"

Q: 应用安装后打开闪退，Logcat 显示 "dlopen failed: empty/missing DT_HASH/DT_GNU_HASH"

Q: 应用启动后几秒闪退，Logcat 显示 "Fatal signal 11 (SIGSEGV), code 2 (SEGV_ACCERR)"

Q: 应用安装后打开闪退（其他原因）

附录：项目目录结构说明

17 KiB

Raw Blame History

改了 Go 代码（`go/` 目录下的文件）

改了 Kotlin 代码（`android/` 目录下的文件）