Android 项目 Operit 编译指南（Linux/Ubuntu）

August 11, 2026 · View on GitHub

本指南详细介绍了在 Linux 环境下（推荐 Ubuntu/Debian）编译 Android 项目 Operit 所需的全部环境配置和步骤。

关于 Operit

Operit AI 是移动端首个功能完备的 AI 智能助手应用，它完全独立运行于您的 Android 设备上，拥有强大的工具调用能力。本项目旨在为开发者提供一个可深度定制和扩展的 AI 助手框架。

在开始编译之前，请确保您已了解本项目的功能和目标。更多信息请参考项目主页的 README.md。

目录

  1. 第一步：安装系统基础依赖
  2. 第二步：安装 Android 命令行工具
  3. 第三步：配置环境变量
  4. 第四步：安装 Android SDK 和 NDK
  5. 附：性能优化 - 配置编译资源
  6. 第五步：克隆并编译项目
  7. 常见问题排查

1. 第一步：安装系统基础依赖

首先，我们需要更新包管理器并安装编译所需的关键基础软件：Git、JDK 21、Node.js、npm 和 Python 3。

# 更新软件包列表  
sudo apt update

# 安装必要的工具、JDK 21、Node.js、npm 和 Python 3
sudo apt install -y git wget unzip openjdk-21-jdk nodejs npm python3

# 安装 pnpm（tools/example_packages/sync_example_packages.py 预构建 examples 时会用到）
sudo npm install -g pnpm

# 安装完成后，请验证 Java 版本是否正确
java -version  
# 预期输出应包含 "OpenJDK Runtime Environment (build 21..." 或类似信息

# 建议同时确认 Node.js、npm、pnpm 和 Python 3 可用
node -v
npm -v
pnpm -v
python3 --version

注意： 项目官方要求 JDK 21。为确保最大兼容性，强烈建议优先安装和使用 JDK 21。

补充说明： 项目中的 web-chat 使用 React + Vite 构建；tools/example_packages/sync_example_packages.py 会预构建 examples/ 下的脚本包并打包 .toolpkg。因此除了 Android 环境外，还需要准备好 Node.js、npm、pnpm 和 Python 3。如果后续执行前端构建时提示 Node.js 版本过低，请升级到较新的 Node.js LTS 版本后再继续。

2. 第二步：安装 Android 命令行工具

为了管理 SDK，我们将使用更轻量的 Android 命令行工具（Command Line Tools），而非庞大的 Android Studio。

  1. 创建 Android SDK 目录:
mkdir -p ~/Android/cmdline-tools
  1. 下载命令行工具:
    访问 Android Developers 官网，复制最新的 Linux 版本链接。
    警告： 下方的链接仅为示例，请务必检查并替换为官方提供的最新链接！
# 示例链接，请务必检查并替换为最新版本  
wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O ~/cmdline-tools.zip
  1. 解压并配置目录结构:
    命令行工具要求其文件位于一个名为 latest 的子目录中，否则 sdkmanager 可能无法识别。
# 解压到目标目录  
unzip ~/cmdline-tools.zip -d ~/Android/cmdline-tools

# 将解压后的 cmdline-tools 移动到 latest 子目录  
mv ~/Android/cmdline-tools/cmdline-tools ~/Android/cmdline-tools/latest

# 清理下载的压缩包  
rm ~/cmdline-tools.zip

最终的工具路径应为 ~/Android/cmdline-tools/latest/bin。

3. 第三步：配置环境变量

配置环境变量以便系统能找到 Java 和 Android SDK 的相关命令，如 java、git 和 sdkmanager。

  1. 编辑配置文件：
nano ~/.bashrc
  1. 在文件末尾添加以下内容：
# =============== Java JDK 21 配置 ===============  
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64  
export PATH=$JAVA_HOME/bin:$PATH

# =============== Android SDK 配置 ===============  
export ANDROID_HOME=$HOME/Android  
# 将 latest/bin 添加到 PATH  
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$PATH  
# 将 platform-tools (ADB/Fastboot) 添加到 PATH  
export PATH=$ANDROID_HOME/platform-tools:$PATH
  1. 使配置生效:
source ~/.bashrc

4. 第四步：安装 Android SDK 和 NDK

使用刚才配置好的 sdkmanager 命令来安装项目所需的 SDK 平台、构建工具和特定版本的 NDK。

  1. 接受所有 SDK 许可 (关键步骤！):
    此步骤是必须的，否则 Gradle 构建会因许可问题而失败。
yes | sdkmanager --licenses
  1. 安装平台工具、SDK 平台和构建工具:
    Operit 项目依赖于 android-34 平台和 34.0.0 构建工具。
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"
  1. 安装项目指定的 NDK 版本:
    本项目要求使用 NDK 25.1.8937393。
sdkmanager "ndk;25.1.8937393"

附：性能优化 - 配置编译资源

对于配置较高的机器（如 16GB 内存或以上），可以通过调整 Gradle 配置来显著加快编译速度。
在项目根目录下的 gradle.properties 文件中，您可以调整以下参数：

# 设置 Gradle 使用的 JVM 最大内存，例如 8GB  
org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError

# 开启并行编译  
org.gradle.parallel=true

# (可选) 设置并行编译的 worker 数量，通常建议设置为 CPU 核心数  
# org.gradle.workers.max=8

5. 第五步：克隆并编译项目

环境准备就绪，现在开始编译项目。

  1. 克隆项目仓库并进入目录:
    请根据需要选择以下两种克隆方式（项目包含 Git 子模块）：

推荐：先 Fork 后克隆你的仓库
在 GitHub 打开上游仓库并点击 Fork： AAswordman/Operit
克隆你的 Fork，并只初始化公开构建依赖 terminal：

git clone https://github.com/<你的 GitHub 用户名>/Operit.git
cd Operit
git submodule update --init --recursive terminal

（可选）添加上游仓库以便同步更新：

git remote add upstream https://github.com/AAswordman/Operit.git

备选：不 Fork，直接克隆上游仓库（只读）

git clone https://github.com/AAswordman/Operit.git
cd Operit
git submodule update --init --recursive terminal

如果你已克隆但尚未初始化公开子模块，可在仓库目录中执行：

git submodule update --init --recursive terminal

其中 DragonBonesCPP、ufbx、Bullet3、Saba、ncnn、sherpa-ncnn、WAMR、llama.cpp、QuickJS、MNN 和 MNN 使用的 KleidiAI 由 CMake 通过 FetchContent 获取。CMake 会先解析远端 ref 的 commit，再下载对应 GitHub archive，因此不会拉取完整 Git 历史；默认跟随各自上游主分支、固定提交或上游工程声明的 tag。如需覆盖某个 ref，可在 CMake 参数中设置 OPERIT_DRAGONBONES_CPP_GIT_REF、OPERIT_UFBX_GIT_REF、OPERIT_BULLET3_GIT_REF、OPERIT_SABA_GIT_REF、OPERIT_NCNN_GIT_REF、OPERIT_SHERPA_NCNN_GIT_REF、OPERIT_WAMR_GIT_REF、OPERIT_LLAMA_CPP_GIT_REF、OPERIT_QUICKJS_GIT_REF、OPERIT_MNN_GIT_REF 或 OPERIT_KLEIDIAI_GIT_REF。

MNN 的 Android CMake 配置会在加入 MNN 子项目前，使用 MNN 自带的 FlatBuffers 源码编译一个宿主机 flatc，并从同一份 schema/default/*.fbs 重新生成 schema/current/*.h。因此构建机除了 Android NDK 和 CMake，还必须提供可用的宿主机 C/C++ 编译器；Linux 构建明确使用 gcc 和 g++，生成器不会使用 Android ABI 编译，也不会依赖工作区外的预生成头文件。

  1. 下载并放置非模型依赖库 (关键步骤！): README.md 中提到，项目依赖一些需要手动下载的库。请从 这个 Google Drive 链接 下载非模型文件，并将它们解压或放置到项目根目录下对应的 libs 或有 .keep 文件的文件夹中。 警告： 如果跳过此步骤，编译将因缺少依赖而失败。当前需要下载并解压这三个压缩包：subpack.zip、jniLibs.zip、libs.zip。默认本地 STT 模型不再通过 models.zip 准备，Android 构建会按 app/config/stt-model-assets.properties 从固定 Hugging Face 来源自动获取并校验。
./app/src/main/assets/subpack/.keep  
./app/src/main/jniLibs/.keep
./app/libs
  1. 切换到你的工作分支 (如果需要):
git checkout docs/add-building-guide
# 将上面的示例分支名替换为你自己创建的分支名
  1. 安装项目根目录的脚本依赖:
npm install

这一步会安装 tools/example_packages/sync_example_packages.py 预构建示例脚本包时需要用到的 typescript、esbuild 等依赖。

  1. 安装 web-chat 的前端依赖:
npm --prefix web-chat install
  1. 先构建 web-chat 并同步到 Android assets (关键步骤！):
npm run build:webchat

该命令会先执行 web-chat 的 React/Vite 构建，再把生成的静态文件同步到 app/src/main/assets/web-chat。如果你修改了 web-chat/src 下的代码，重新编译 APK 前也需要重新执行一次这一步。

  1. 打包 ToolPkg 并同步示例包到应用 assets (关键步骤！):
python3 ./tools/example_packages/sync_example_packages.py

该命令会按 tools/example_packages/packages_whitelist.txt 预构建 examples/ 下的脚本包，并将包含 manifest.json 或 manifest.hjson 的目录打包成 .toolpkg，最终输出到 app/src/main/assets/packages/。如果你修改了 examples/ 下的脚本包代码，重新编译 APK 前也需要重新执行一次这一步。

  1. 为 Gradle 包装器添加可执行权限:
chmod +x ./gradlew
  1. 运行 assembleDebug 命令进行编译:
    首次编译会下载大量依赖，请耐心等待。
./gradlew assembleDebug

或者运行 assembleDebugClone 编译共存版:

./gradlew assembleDebugClone
  1. 查找 APK 文件:
    编译成功后，生成的 APK 文件位于项目目录下的以下路径：
    app/build/outputs/apk/debug/app-debug.apk app/build/outputs/apk/clone/app-clone.apk

7. 常见问题排查

错误信息解决方案
sdkmanager: command not found环境变量未正确设置或生效。请检查 ~/.bashrc 文件内容，并执行 source ~/.bashrc。
Could not determine Java version...JAVA_HOME 环境变量不正确，或安装了错误的 JDK 版本。请确保已安装 JDK 21 并指向正确的路径。
NDK not found.确保已在 第四步 中使用 sdkmanager 安装了项目所需的 ndk;25.1.8937393 版本。
pnpm: command not found尚未安装 pnpm。请先执行 sudo npm install -g pnpm，再重新运行 python3 ./tools/example_packages/sync_example_packages.py。
Missing web-chat/dist. Run npm --prefix web-chat run build first.尚未构建 web-chat 或构建失败。请先执行 npm --prefix web-chat install，再在项目根目录执行 npm run build:webchat。
ERROR: prebuild step failedtools/example_packages/sync_example_packages.py 在预构建 examples/ 时失败。请先确认已在项目根目录执行 npm install，并检查 pnpm -v、python3 --version 是否可用。
Failed to build the host FlatBuffers compilerMNN schema 生成阶段无法找到或运行宿主机 C/C++ 工具链。Linux 请安装 gcc 和 g++，其他平台请安装与当前平台匹配的编译器后重新运行 Gradle 构建。
You have not accepted the license agreements...你跳过了或未成功执行接受许可的步骤。请返回 第四步 执行 `yes