1. 为什么我要自己编译 ArmorPaintArmorPaint 这个软件圈内人应该不陌生。它是一个开源的 3D 模型纹理绘制工具主打 PBR 材质绘制支持直接在模型表面画贴图功能上对标 Substance Painter 那一类商业软件。官方提供的是付费下载的预编译版本源码托管在公开仓库里采用比较特殊的授权模式——源码开放但官方编译好的二进制包需要付费购买。这就意味着如果你不想花钱或者想自己改点东西那就得自己从源码编译。我最初接触 ArmorPaint 是因为接了一个独立游戏的外包需要给一批低模角色画手绘风格的贴图。Substance Painter 的订阅费对我来说有点肉疼Blender 自带的纹理绘制功能又太基础图层混合和笔刷系统都不够用。找了一圈ArmorPaint 是最合适的选择。但官方编译版要花钱而且我后来发现官方版本在某些 Linux 发行版上跑起来有问题显卡驱动兼容性也不太好。于是我就动了自己编译的念头。这一编译就踩了整整三天的坑。从环境配置到依赖拉取从编译报错到运行闪退几乎每个环节都卡过我。网上关于 ArmorPaint 编译的中文资料少得可怜官方文档写得也比较简略很多细节要靠自己摸索。所以我把整个编译过程整理出来包括我遇到的所有问题和解决方案希望能帮到后面想自己编译的朋友。这篇文章适合几类人一是想白嫖 ArmorPaint 但不想付费的开发者二是需要在特定平台上运行 ArmorPaint 的用户比如某些 Linux 发行版或者老版本的 Windows三是想自己修改源码、定制功能的进阶玩家。如果你只是想在 Windows 上随便用用那直接买官方版可能更省事。但如果你有编译需求或者想深入了解这个软件的架构那这篇内容应该能帮你省下不少时间。2. 编译前的环境准备与工具选型2.1 硬件与操作系统的选择ArmorPaint 的编译对硬件要求不算特别高但也不是随便一台机器就能跑。我实测下来编译过程主要吃 CPU 和内存显卡反而不是编译阶段的瓶颈。我的主力机是 AMD Ryzen 7 5800X32GB 内存编译一次大概需要 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-devmacOS 上相对简单大部分库系统自带但你可能需要装 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 上一般是 x64Linux 上也是 x64macOS 上现在有 x64 和 arm64Apple 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或openglLinux 上推荐opengl或vulkanmacOS 上只能用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这一步可能会比较慢因为子模块不少。如果卡在某个子模块上可以按 CtrlC 中断然后进入 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 有时候会有权限问题我最后还是用了官网的二进制包。然后安装 Khahaxelib 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 和 OpenALbrew install sdl2 openal-softHaxe 和 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.app4.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这通常是因为子模块的版本冲突。比如你手动更新了某个子模块导致同一个类被定义了两次。解决办法是回退子模块到主仓库指定的 commitgit 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-devWindows 上确保 Windows SDK 里有 OpenGL 的库。LNK2019: unresolved external symbolWindows 上常见的链接错误通常是某个库没有正确链接。检查 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 常见问题速查表问题现象可能原因解决方案编译时报Type not foundKha 版本不匹配回退 Kha 到源码指定的版本链接时报undefined reference缺少依赖库安装对应的开发库运行时报Failed to create OpenGL context显卡驱动问题更新显卡驱动加载模型时闪退模型文件不标准用 Blender 重新导出界面显示异常图形 API 不兼容换用其他图形 API 编译编译速度极慢Debug 模式或硬件不足用 Release 模式升级硬件程序启动后黑屏分辨率或缩放问题修改配置文件或命令行参数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 这件事最难的不是技术本身而是耐心。因为资料少很多问题要靠自己摸索有时候一个报错要查半天。但一旦编译成功那种成就感是很足的。而且通过编译你对这个软件的理解会更深入用起来也更得心应手。如果你也在编译过程中遇到问题欢迎交流我尽量帮你避坑。