ArmorPaint 源码编译实战：从环境配置到运行调试的完整避坑指南

1. 为什么我要自己编译 ArmorPaint

ArmorPaint 这个软件，圈内人应该不陌生。它是一个开源的 3D 模型纹理绘制工具，主打 PBR 材质绘制，支持直接在模型表面画贴图，功能上对标 Substance Painter 那一类商业软件。官方提供的是付费下载的预编译版本，源码托管在公开仓库里，采用比较特殊的授权模式——源码开放，但官方编译好的二进制包需要付费购买。这就意味着，如果你不想花钱，或者想自己改点东西，那就得自己从源码编译。

我最初接触 ArmorPaint 是因为接了一个独立游戏的外包，需要给一批低模角色画手绘风格的贴图。Substance Painter 的订阅费对我来说有点肉疼，Blender 自带的纹理绘制功能又太基础，图层混合和笔刷系统都不够用。找了一圈，ArmorPaint 是最合适的选择。但官方编译版要花钱，而且我后来发现官方版本在某些 Linux 发行版上跑起来有问题，显卡驱动兼容性也不太好。于是我就动了自己编译的念头。

这一编译，就踩了整整三天的坑。从环境配置到依赖拉取，从编译报错到运行闪退，几乎每个环节都卡过我。网上关于 ArmorPaint 编译的中文资料少得可怜，官方文档写得也比较简略，很多细节要靠自己摸索。所以我把整个编译过程整理出来，包括我遇到的所有问题和解决方案，希望能帮到后面想自己编译的朋友。

这篇文章适合几类人：一是想白嫖 ArmorPaint 但不想付费的开发者；二是需要在特定平台上运行 ArmorPaint 的用户，比如某些 Linux 发行版或者老版本的 Windows；三是想自己修改源码、定制功能的进阶玩家。如果你只是想在 Windows 上随便用用，那直接买官方版可能更省事。但如果你有编译需求，或者想深入了解这个软件的架构，那这篇内容应该能帮你省下不少时间。

2. 编译前的环境准备与工具选型

2.1 硬件与操作系统的选择

ArmorPaint 的编译对硬件要求不算特别高，但也不是随便一台机器就能跑。我实测下来，编译过程主要吃 CPU 和内存，显卡反而不是编译阶段的瓶颈。我的主力机是 AMD Ryzen 7 5800X，32GB 内存，编译一次大概需要 8 到 12 分钟。如果你用的是笔记本低压 U，比如 i5-10210U 这种，编译时间可能会拉长到 20 分钟以上，而且内存如果只有 8GB，大概率会在链接阶段爆内存。

操作系统方面，官方主要支持 Windows、Linux 和 macOS。我三个平台都试过，Windows 上编译最省心，因为官方提供了预编译的依赖库；Linux 上最折腾，不同发行版的包管理器和库版本差异很大；macOS 上介于两者之间，但 Xcode 的版本兼容性需要注意。如果你只是想快速得到一个可用的编译版，我建议在 Windows 上操作，用 Visual Studio 2022 作为编译工具链。

具体来说，Windows 10 或 Windows 11 都可以，但要注意系统版本不能太老。我试过在 Windows 8.1 上编译，结果因为缺少某些系统 API 导致编译失败。Linux 方面，Ubuntu 20.04 和 22.04 是比较稳妥的选择，Arch 系虽然包新，但滚动更新容易导致依赖版本对不上。macOS 建议用 12 以上的版本，Xcode 命令行工具要装好。

2.2 编译工具链的安装与配置

ArmorPaint 是用 Haxe 语言写的，然后通过 Kha 框架跨平台编译。所以你需要的不只是 C++ 编译器，还要装 Haxe 工具链和 Kha 的相关依赖。这是很多人第一次编译时最容易懵的地方——以为是个普通的 C++ 项目，结果发现构建系统完全不是那回事。

首先说 Haxe。你需要去 Haxe 官网下载对应平台的安装包，版本建议用 4.2.5 或 4.3.0，太新的版本有时候会和 Kha 的某些库不兼容。安装完之后，打开终端或命令行，输入haxe -version确认安装成功。然后需要安装 Haxelib，这是 Haxe 的包管理器，类似 Node.js 的 npm 或者 Python 的 pip。装好 Haxelib 之后，你需要通过它安装 Kha 框架。

Kha 的安装命令是haxelib install kha，但这里有个坑——Kha 的版本更新很快，而 ArmorPaint 的源码可能只兼容特定版本的 Kha。我建议先去看 ArmorPaint 源码根目录下的khafile.js或者haxelib.json，里面会写明依赖的 Kha 版本。如果没有写明，那就用haxelib install kha装最新版，然后祈祷能编译通过。我试过用 Kha 的最新版编译 ArmorPaint 0.9 的源码，结果报了一堆 API 不兼容的错误，后来回退到 Kha 22.10 才搞定。

除了 Haxe 和 Kha，你还需要一个 C++ 编译器。Windows 上用 Visual Studio 2022 的 MSVC 工具链，安装的时候记得勾选“使用 C++ 的桌面开发”工作负载。Linux 上用 GCC 或 Clang 都行，但要注意版本，GCC 9 以上比较稳妥。macOS 上用 Xcode 自带的 Clang。另外，Git 也是必须的，因为你需要从仓库拉取源码和子模块。

2.3 依赖库的拉取与版本管理

ArmorPaint 的依赖库不少，包括但不限于：SDL2、OpenGL 或 Vulkan 的 SDK、各种图像编解码库（如 stb_image）、物理引擎（如 Bullet 或 ODE，用于某些碰撞检测功能）。这些依赖大部分可以通过 Kha 的构建系统自动拉取，但有些需要你手动安装。

在 Windows 上，Kha 会自动下载预编译的依赖库，你基本不用操心。但在 Linux 上，你需要通过包管理器安装一些系统级的库，比如libsdl2-dev、libgl1-mesa-dev、libopenal-dev等等。具体缺哪些，编译报错的时候会告诉你。我建议在 Ubuntu 上先把这一串装上：

sudo apt-get install libsdl2-dev libgl1-mesa-dev libopenal-dev libx11-dev libxext-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev libasound2-dev libpulse-dev

macOS 上相对简单，大部分库系统自带，但你可能需要装 SDL2 和 OpenAL。用 Homebrew 装就行：brew install sdl2 openal-soft。

这里有个经验：依赖库的版本不要盲目追新。我试过在 Ubuntu 22.04 上用系统自带的 SDL2 2.26，结果编译出来的 ArmorPaint 运行时报错，说某个符号找不到。后来换成 SDL2 2.0.20 的源码自己编译安装，问题就解决了。所以如果你在 Linux 上遇到奇怪的链接错误，先检查一下依赖库的版本。

3. 源码获取与编译参数详解

3.1 从仓库拉取源码的正确姿势

ArmorPaint 的源码托管在 GitHub 上，仓库地址是https://github.com/armory3d/armorpaint。但你不能直接git clone就完事，因为它用了子模块（submodule）。如果你直接 clone 主仓库，很多依赖目录是空的，编译的时候会报找不到文件。

正确的做法是：

git clone --recursive https://github.com/armory3d/armorpaint.git

如果你已经 clone 了但忘了加--recursive，可以进入目录后执行：

git submodule update --init --recursive

这一步会拉取 Kha、Iron、Armory 等子模块。网络状况不好的话，可能会卡住或者失败。我建议在拉取之前先配置一下 Git 的代理，或者用国内的一些镜像源。不过要注意，子模块的版本必须和主仓库的 commit 对应，不要手动去改子模块的版本，否则编译大概率出问题。

拉取完成后，检查一下目录结构。根目录下应该有Sources、Assets、Kha、Libraries等文件夹。如果Kha文件夹是空的，说明子模块没拉下来，需要重新执行上面的命令。

3.2 编译目标平台与架构的选择

ArmorPaint 支持编译到多个平台：Windows、Linux、macOS、Android、HTML5 等。但不同平台的编译流程和依赖差异很大。我主要关注桌面端，所以这里只讲 Windows、Linux 和 macOS 的编译。

在编译之前，你需要确定目标架构。Windows 上一般是 x64，Linux 上也是 x64，macOS 上现在有 x64 和 arm64（Apple Silicon）两种。如果你用的是 M1 或 M2 的 Mac，编译的时候需要指定 arm64 架构，否则编译出来的程序在 Rosetta 下跑性能会打折扣。

Kha 的构建系统通过khafile.js来配置编译目标。你可以在根目录下找到这个文件，里面有一行let target = ...，默认可能是windows或linux。如果你想编译到其他平台，需要修改这个变量。不过更推荐的方式是通过命令行参数来指定，比如：

node Kha/make.js --target windows --arch x64

这样不会污染源码文件，也方便切换。

3.3 关键编译参数的解读与设置

Kha 的构建系统提供了一系列参数，常用的有：

• --target：指定目标平台，如windows、linux、macos、android、html5。
• --arch：指定架构，如x64、arm64、x86。
• --debug：编译 Debug 版本，包含调试符号，运行速度慢但方便排查问题。
• --release：编译 Release 版本，开启优化，运行速度快，但调试信息少。
• --graphics：指定图形 API，如opengl、vulkan、direct3d11。这个参数很关键，选错了可能导致程序无法启动。

我一般先用 Debug 模式编译一次，确认能跑起来，再用 Release 模式编译最终版本。图形 API 方面，Windows 上推荐direct3d11或opengl，Linux 上推荐opengl或vulkan，macOS 上只能用opengl或metal（但 Kha 对 Metal 的支持不太完善，建议用 OpenGL）。

还有一个参数是--kha，用来指定 Kha 的路径。如果你把 Kha 放在非标准位置，需要手动指定。一般情况下不用管，构建脚本会自动找到。

编译命令的完整形式大概是这样的：

node Kha/make.js --target windows --arch x64 --graphics opengl --release

执行这个命令后，Kha 会先调用 Haxe 编译器把 Haxe 代码编译成 C++ 代码，然后再调用 C++ 编译器把 C++ 代码编译成可执行文件。整个过程可能需要几分钟到十几分钟，取决于你的机器性能。

4. 实操编译全流程与踩坑记录

4.1 Windows 平台编译实录

我在 Windows 上编译过三次，第一次花了整整一个下午，后面两次就快多了。下面是我总结的完整流程。

第一步，安装 Visual Studio 2022。去官网下载 Community 版，安装的时候勾选“使用 C++ 的桌面开发”，确保 MSVC 编译器和 Windows SDK 都装上。安装完成后，打开“Developer Command Prompt for VS 2022”，后续的编译命令都在这个命令行里执行，因为它会自动配置好环境变量。

第二步，安装 Haxe 和 Haxelib。去 Haxe 官网下载 Windows 安装包，一路下一步就行。装完后打开命令行，输入haxe -version确认。然后输入haxelib setup，指定一个目录存放 Haxelib 的包，默认是C:\HaxeToolkit\haxelib或者用户目录下的haxelib文件夹。

第三步，安装 Kha。在命令行里执行：

haxelib install kha

如果网络慢，可以加上--always参数跳过确认。装完后执行haxelib list确认 Kha 已经安装。

第四步，拉取 ArmorPaint 源码。找个合适的目录，执行：

git clone --recursive https://github.com/armory3d/armorpaint.git

这一步可能会比较慢，因为子模块不少。如果卡在某个子模块上，可以按 Ctrl+C 中断，然后进入 ArmorPaint 目录，手动执行git submodule update --init --recursive，多试几次。

第五步，编译。进入 ArmorPaint 目录，执行：

node Kha/make.js --target windows --arch x64 --graphics opengl --release

然后就是等待。编译过程中会输出大量日志，如果看到红色的错误信息，就要停下来排查。我第一次编译的时候，报错说找不到SDL2.h，原因是 Kha 没有自动下载 SDL2 的预编译库。解决办法是手动去 Kha 的Kinc目录下执行git submodule update --init --recursive，把 Kinc 的子模块也拉下来。

编译成功后，可执行文件会生成在build\x64\Release目录下，名字叫ArmorPaint.exe。双击运行，如果能看到界面，说明编译成功了。

4.2 Linux 平台编译实录

Linux 上的编译比 Windows 麻烦一些，主要是依赖库的问题。我用的是 Ubuntu 22.04，下面是我踩过的坑。

首先，Haxe 和 Haxelib 的安装。Ubuntu 的 apt 源里有 Haxe，但版本可能比较老。我建议去 Haxe 官网下载 Linux 的二进制包，解压后把haxe和haxelib加到 PATH 里。或者用 snap 安装：sudo snap install haxe。但 snap 版本的 Haxelib 有时候会有权限问题，我最后还是用了官网的二进制包。

然后安装 Kha：haxelib install kha。这一步和 Windows 一样。

接下来是依赖库。Ubuntu 上需要装一堆开发库，前面已经列过了。但有个坑：Ubuntu 22.04 的libsdl2-dev版本是 2.0.20，而 Kha 可能期望的是 2.0.18 或更早的版本。我编译的时候报错说SDL_GetWindowDisplayIndex符号找不到，后来发现是 SDL2 版本太新，某些 API 变了。解决办法是去 SDL2 官网下载 2.0.18 的源码，自己编译安装：

wget https://www.libsdl.org/release/SDL2-2.0.18.tar.gz tar -xzf SDL2-2.0.18.tar.gz cd SDL2-2.0.18 ./configure --prefix=/usr/local make -j$(nproc) sudo make install

然后重新编译 ArmorPaint，问题解决。

还有一个坑是 OpenGL 的驱动。如果你用的是 NVIDIA 显卡，需要装好闭源驱动，否则编译出来的程序运行时会报Failed to create OpenGL context。AMD 和 Intel 的核显一般用开源驱动就行，但也要确保mesa-utils装好了。

编译命令和 Windows 类似：

node Kha/make.js --target linux --arch x64 --graphics opengl --release

编译成功后，可执行文件在build/linux/Release目录下，名字叫ArmorPaint。直接运行就行，如果报错缺少动态库，用ldd ArmorPaint查看缺哪个，然后装上对应的库。

4.3 macOS 平台编译实录

macOS 上编译 ArmorPaint 的人相对少一些，但我也试过。主要问题是 Xcode 的版本和命令行工具的配置。

首先，确保你装了 Xcode 命令行工具：xcode-select --install。然后装 Homebrew，用 Homebrew 装 SDL2 和 OpenAL：

brew install sdl2 openal-soft

Haxe 和 Haxelib 的安装和 Linux 类似，去官网下载 macOS 的二进制包，解压后加到 PATH。然后haxelib install kha。

编译命令：

node Kha/make.js --target macos --arch x64 --graphics opengl --release

如果你用的是 Apple Silicon 的 Mac，把--arch改成arm64。但要注意，Kha 对 arm64 的支持可能不完善，我试过编译 arm64 版本，结果运行时报错说某个汇编指令不支持。后来还是用 x64 版本通过 Rosetta 运行，性能损失大概 10% 到 15%，但至少能用。

macOS 上还有一个坑是代码签名。编译出来的.app包默认没有签名，双击运行会被 Gatekeeper 拦截。解决办法是在“系统偏好设置”->“安全性与隐私”里允许运行，或者用codesign命令手动签名：

codesign --force --deep --sign - build/macos/Release/ArmorPaint.app

4.4 编译后的运行测试与性能调优

编译成功只是第一步，能不能稳定运行才是关键。我编译出来的第一个版本，启动后界面能显示，但一加载模型就闪退。查了日志发现是显卡驱动的问题——我的 NVIDIA 驱动版本太老，不支持 ArmorPaint 用到的某个 OpenGL 扩展。更新驱动后问题解决。

性能方面，Release 版本比 Debug 版本快很多。我实测在同一个模型上绘制纹理，Debug 版本帧率只有 20 多，Release 版本能到 60 以上。所以最终使用一定要用 Release 版本。

另外，ArmorPaint 的渲染设置里可以调整分辨率缩放和抗锯齿级别。如果你的显卡性能一般，可以把分辨率缩放调到 0.75 或 0.5，帧率会明显提升。抗锯齿建议用 FXAA，比 MSAA 省资源。

还有一个调优技巧：在khafile.js里可以开启或关闭某些编译选项，比如--no-compress可以加快编译速度但生成的二进制更大，--optimize可以开启更激进的优化但编译时间更长。我一般用默认配置，除非有特殊需求。

5. 常见编译错误与排查手册

5.1 Haxe 编译阶段的典型报错

Haxe 编译阶段的报错通常和版本不兼容有关。我遇到最多的就是Type not found或者Field not found，这多半是因为 Kha 的版本和 ArmorPaint 源码不匹配。解决办法是查看 ArmorPaint 仓库的haxelib.json，里面会写明依赖的 Kha 版本。如果没有写明，就去 GitHub 的 commit 历史里找，看看最近一次成功编译的 commit 对应的 Kha 版本是多少。

另一个常见报错是Duplicate class field declaration，这通常是因为子模块的版本冲突。比如你手动更新了某个子模块，导致同一个类被定义了两次。解决办法是回退子模块到主仓库指定的 commit：

git submodule update --init --recursive --force

还有一个报错是Uncaught exception - load.c(237) : Failed to load library : kha，这说明 Kha 没有正确安装或者 Haxelib 的路径不对。检查haxelib list里有没有 Kha，如果没有就重新安装。如果路径不对，用haxelib setup重新配置。

5.2 C++ 链接阶段的疑难杂症

C++ 链接阶段的报错通常更棘手，因为涉及系统库和第三方库。我遇到过的典型报错包括：

• undefined reference to 'SDL_Init'：缺少 SDL2 库。Windows 上检查 Kha 的 Kinc 子模块是否拉取完整；Linux 上检查libsdl2-dev是否安装；macOS 上检查 Homebrew 的 SDL2 是否链接正确。
• cannot find -lGL：缺少 OpenGL 库。Linux 上装libgl1-mesa-dev，Windows 上确保 Windows SDK 里有 OpenGL 的库。
• LNK2019: unresolved external symbol：Windows 上常见的链接错误，通常是某个库没有正确链接。检查 Visual Studio 的项目配置，确保所有依赖库的路径都加到了链接器里。

如果链接错误太多，可以尝试用 Debug 模式编译，因为 Debug 模式会输出更详细的错误信息。另外，清理一下构建缓存也有帮助：

rm -rf build

然后重新编译。

5.3 运行时崩溃与闪退的排查思路

编译成功但运行崩溃，这种问题最让人头疼。我的排查思路是：

第一，看日志。ArmorPaint 运行时会输出日志到控制台，Windows 上可以在命令行里运行ArmorPaint.exe查看输出，Linux 和 macOS 上直接在终端里运行。日志里通常会有错误信息，比如Failed to create window或者Shader compilation failed。

第二，检查显卡驱动。很多运行时崩溃都是显卡驱动引起的。确保你的显卡驱动是最新的，而且支持 ArmorPaint 需要的 OpenGL 版本（至少 OpenGL 3.3）。

第三，检查模型文件。有些模型文件格式不标准，加载时会崩溃。试试用 Blender 重新导出模型，或者换一个简单的模型测试。

第四，检查内存。ArmorPaint 在处理高面数模型时会吃很多内存，如果内存不足会直接崩溃。打开任务管理器看看内存占用，如果接近 100%，那就需要升级内存或者简化模型。

5.4 常见问题速查表

6. 编译版的使用体验与后续扩展

6.1 编译版和官方版的差异对比

自己编译的 ArmorPaint 和官方付费版在功能上基本一致，因为源码是同一套。但有几个细微差别：

第一，官方版会定期更新，修复 bug 和添加新功能。你自己编译的版本取决于你拉取的源码版本，如果你不主动更新，就会停留在旧版本。

第二，官方版可能包含一些闭源的插件或资源，比如某些高级笔刷或材质库。编译版只有开源的部分，这些额外资源需要自己找或者自己制作。

第三，官方版有代码签名，Windows 和 macOS 上不会触发安全警告。编译版没有签名，运行时可能会被系统拦截，需要手动允许。

第四，官方版的技术支持更完善，遇到问题可以找官方客服。编译版只能自己排查，或者去社区求助。

不过，编译版也有优势：你可以自己修改源码，定制功能。比如我改过笔刷的默认参数，把某些常用笔刷的硬度调高了一点，用起来更顺手。我还改过界面布局，把常用的工具按钮放到了更顺手的位置。这些定制在官方版里是做不到的。

6.2 我个人的使用感受与优化建议

用了一段时间编译版，整体感受是：能用，但需要折腾。如果你只是想画贴图，不想折腾编译，那官方版更省心。但如果你喜欢折腾，或者有特殊需求，编译版的可玩性更高。

优化建议方面，我总结了几个点：

• 定期更新源码。ArmorPaint 的开发比较活跃，每隔几个月就有新功能。定期git pull然后重新编译，可以体验到最新功能。
• 备份你的修改。如果你改了源码，记得用 Git 分支管理，否则更新的时候会冲突。
• 加入社区。ArmorPaint 的 Discord 和 GitHub Issues 里有很多有用的信息，遇到问题可以先搜一下。
• 关注性能。编译版默认可能没有开启所有优化，你可以在khafile.js里调整编译参数，比如开启 LTO（链接时优化）来提升性能。

6.3 后续可以尝试的扩展方向

如果你已经成功编译了 ArmorPaint，可以尝试一些扩展方向：

第一，编译到其他平台。比如 Android 或 HTML5，虽然功能可能不完整，但可以体验一下移动端或网页端的纹理绘制。

第二，修改源码添加自定义功能。比如添加新的笔刷类型，或者集成其他开源库。ArmorPaint 的代码结构比较清晰，Haxe 语言也不难学，有编程基础的话可以试试。

第三，制作自己的材质库。ArmorPaint 支持导入自定义材质，你可以用其他工具制作 PBR 材质，然后导入到 ArmorPaint 里使用。

第四，参与开源贡献。如果你修复了某个 bug 或者添加了某个功能，可以给官方仓库提 Pull Request，帮助其他用户。

我在实际操作中的体会是，编译 ArmorPaint 这件事，最难的不是技术本身，而是耐心。因为资料少，很多问题要靠自己摸索，有时候一个报错要查半天。但一旦编译成功，那种成就感是很足的。而且通过编译，你对这个软件的理解会更深入，用起来也更得心应手。如果你也在编译过程中遇到问题，欢迎交流，我尽量帮你避坑。