1. 为什么我要自己编译 ArmorPaintArmorPaint 这个软件圈子里做 3D 纹理绘制的人应该不陌生。它是一款开源的 3D 模型纹理绘制工具定位上跟 Substance Painter 属于同一赛道支持 PBR 材质绘制、图层系统、粒子笔刷、节点材质编辑还能直接导出到主流游戏引擎和渲染器。但它的官方发行方式一直有点特殊源码在 GitHub 上公开但官方编译好的二进制包需要付费购买才能下载。这就导致很多想先试试手感、或者纯粹想学习研究的人卡在了第一步。我自己是从 2021 年前后开始接触 ArmorPaint 的。当时手上有个独立游戏项目需要给一批低模角色画贴图商业软件授权费对个人开发者来说压力不小就想着找个开源替代方案。ArmorPaint 的功能列表看起来很对胃口但官网下载页面那个价格标签让我犹豫了很久。后来发现它的源码是完整开放的编译文档也写得比较清楚就动了自己编译的念头。这一路踩的坑不算少。从依赖库版本对不上到编译到一半报链接错误再到编译出来的程序跑起来闪退前后折腾了大概两周才跑通一个稳定版本。后来我又在不同配置的机器上重复了几次编译流程慢慢总结出一套比较靠谱的操作路径。这篇文章就是把这套流程完整记录下来包括环境准备、依赖处理、编译参数、常见报错和排查方法以及编译版和官方付费版在实际使用中的差异。需要先说明一点ArmorPaint 的源码采用 zlib 许可证允许自由使用、修改和分发自己编译用于个人学习或内部项目是完全合规的。但如果你打算把编译版用于商业生产环境建议还是去官网购买官方版本一方面支持开发者持续维护另一方面官方版有自动更新和预编译的便利性。我分享编译经验的目的是帮助那些想学习编译流程、想在特定平台上做定制化修改、或者单纯想先验证软件是否适合自己的朋友。这篇文章适合几类人看一是对 3D 纹理绘制工具有兴趣、想低成本入门的独立开发者二是想学习如何从源码编译图形类应用程序的编程爱好者三是已经在用 ArmorPaint 但想了解编译版和官方版差异的老用户。不管你之前有没有编译过 C 或图形类项目我会尽量把每一步都讲清楚包括那些文档里没写但实际操作中一定会遇到的问题。2. 编译前的环境准备与依赖梳理2.1 硬件与操作系统的选择ArmorPaint 基于 Haxe 语言和 Kha 引擎开发底层会调用 OpenGL 或 Direct3D 进行渲染。这意味着它对显卡驱动和图形 API 的支持有一定要求。我实测下来Windows 10 和 Windows 11 是最省心的平台Linux 下也能编译但需要额外处理一些图形库的依赖macOS 则因为 Metal 后端的适配问题编译成功率相对低一些。硬件方面编译过程本身对 CPU 和内存的要求不算高四核处理器加 8GB 内存就能跑完整个编译流程。但编译出来的程序要流畅运行显卡至少得支持 OpenGL 4.4 或更高版本。我手头一台老笔记本用的是集成显卡编译能过但打开软件后画布渲染明显卡顿换到带独立显卡的台式机上就顺畅很多。所以如果你打算长期用建议在带独立显卡的机器上操作。磁盘空间方面源码仓库加上编译中间产物和最终二进制大概需要 3 到 5 GB。如果同时保留多个版本的编译结果空间还要再留宽裕一些。我一般会单独分一个工作目录把所有相关文件都放在里面方便管理和清理。2.2 核心工具链的安装与版本匹配编译 ArmorPaint 需要几个核心工具Git 用于拉取源码Haxe 编译器用于编译 Haxe 代码Kha 作为底层框架需要单独获取另外还需要一个 C 编译器来处理底层的原生代码。在 Windows 上我推荐用 Visual Studio 的 MSVC 工具链在 Linux 上则是 GCC 或 Clang。这里有个关键点Haxe 的版本不能太新也不能太旧。我试过用最新的 Haxe 5.x 去编译结果 Kha 框架里有些语法不兼容报了一堆类型错误。后来退回到 Haxe 4.2.x 系列就顺利通过了。具体来说4.2.5 是我实测最稳定的版本。Kha 框架也要选对分支ArmorPaint 的源码里通常会指定一个兼容的 Kha 提交哈希直接克隆 Kha 的主分支可能会遇到 API 变动导致的编译失败。Git 的安装没什么特别的官网下载安装包一路下一步就行。Haxe 建议用官方提供的安装程序安装完成后在命令行里执行haxe --version确认版本号。Kha 的获取方式是在命令行里用 Git 克隆然后切换到 ArmorPaint 源码中指定的那个提交。如果你不确定该用哪个提交可以看 ArmorPaint 仓库根目录下的khafile.js或者相关的配置文件里面通常会写明依赖的 Kha 版本信息。C 编译器方面Windows 上安装 Visual Studio 时记得勾选“使用 C 的桌面开发”工作负载这样会自带 MSVC 编译器和 Windows SDK。Linux 上一般用包管理器安装 build-essential 就能满足基本需求但可能还需要额外安装一些图形库的开发包比如 libgl1-mesa-dev、libx11-dev 之类的。2.3 依赖库的获取与目录结构规划ArmorPaint 的源码仓库里包含了一个armorcore子模块这是它的核心渲染和逻辑层。克隆源码时一定要加上--recursive参数否则子模块不会自动拉取编译时就会报找不到头文件的错误。我见过不少人卡在这一步以为是编译器配置问题其实是子模块没拉全。目录结构我习惯这样安排建一个总目录叫armorpaint-build里面放三个子目录分别是armorpaint主源码、kha框架源码和tools存放 Haxe 和其他工具。这样做的原因是 Kha 在编译时会通过相对路径去查找 ArmorPaint 的源码如果目录层级不对编译脚本就会找不到文件。具体的路径关系可以在 ArmorPaint 的编译脚本里看到通常是假设 Kha 和 ArmorPaint 处于同一级目录。另外Haxe 的库管理工具 haxelib 也需要提前配置好。ArmorPaint 依赖几个 Haxe 库比如format、hxbit之类的这些可以通过 haxelib 自动安装也可以手动下载放到指定目录。我建议先用 haxelib 安装命令是haxelib install format这样逐个装。如果网络环境导致下载慢可以配置国内镜像源具体方法这里不展开但思路就是修改 haxelib 的仓库地址。注意整个编译过程中路径里尽量不要出现中文或空格。我试过把源码放在“我的文档”下面结果编译脚本在处理路径时出了乱码问题排查了很久才发现是路径字符集的事。后来统一放到纯英文、无空格的路径下就再没出过类似问题。3. 从源码到可执行文件的完整编译流程3.1 拉取源码与子模块初始化第一步是克隆 ArmorPaint 的主仓库。打开命令行切换到你规划好的工作目录执行git clone --recursive https://github.com/armory3d/armorpaint.git这个命令会把主仓库和所有子模块一起拉下来。如果中途网络中断导致子模块没拉全可以进入armorpaint目录后执行git submodule update --init --recursive来补全子模块。拉完之后检查一下armorpaint/armorcore目录下是否有文件如果是个空目录说明子模块没拉成功需要重新执行上面的命令。接下来获取 Kha 框架。在armorpaint的同级目录下执行git clone https://github.com/Kode/Kha.git kha克隆完成后需要切换到与 ArmorPaint 兼容的提交。这个提交哈希可以在 ArmorPaint 仓库的khafile.js或者armorcore的配置文件中找到线索。我通常的做法是先用 Kha 的主分支试编译如果报错再去查 ArmorPaint 最近的提交记录看它更新 Kha 子模块时用的是哪个版本。找到对应的提交哈希后在kha目录下执行git checkout 提交哈希切换过去。3.2 配置编译参数与生成项目文件ArmorPaint 的编译入口是一个叫make.js的脚本位于主源码目录下。这个脚本会调用 Kha 的编译工具链根据你传入的参数生成对应平台的项目文件。在 Windows 上我一般用这样的命令node make.js --graphics direct3d11 --compile这里的--graphics参数指定图形后端Windows 上可以用direct3d11或openglLinux 上通常用opengl。--compile表示生成项目文件后立即开始编译。如果你只想生成项目文件而不马上编译可以去掉--compile之后用 Visual Studio 打开生成的解决方案手动编译。执行这个命令之前确保node命令可用。Kha 的编译工具是用 Node.js 写的所以需要提前安装 Node.js。版本方面我用的 16.x 和 18.x 都正常太老的版本可能不支持某些语法。命令执行后会在armorpaint/build目录下生成对应平台的项目文件。Windows 上是一个 Visual Studio 的.sln解决方案Linux 上则是 Makefile。如果这一步报错常见原因是 Haxe 或 haxelib 的路径没配置好或者 Kha 的版本不匹配。错误信息通常会提示找不到某个模块或类型根据提示去检查对应的依赖即可。3.3 执行编译与处理链接错误如果上一步用了--compile参数编译会自动开始。否则需要手动打开生成的项目文件进行编译。在 Windows 上我习惯用命令行调用 MSBuildmsbuild armorpaint.sln /p:ConfigurationRelease /p:Platformx64用 Release 配置编译出来的程序体积更小、运行更快Debug 配置主要用于排查问题。编译过程大概持续五到十分钟取决于机器性能。编译成功后可执行文件会出现在armorpaint/build/x64/Release目录下文件名通常是ArmorPaint.exe。链接阶段最容易遇到的错误是找不到某些系统库。比如在 Windows 上可能会提示找不到d3d11.lib或dxgi.lib这说明 Windows SDK 的版本不对或者没安装完整。解决办法是打开 Visual Studio Installer确认“Windows 10 SDK”或“Windows 11 SDK”已经勾选安装。Linux 上则可能是找不到libGL.so或libX11.so通过包管理器安装对应的开发包即可。还有一个比较隐蔽的问题编译出来的程序依赖一些动态链接库比如msvcp140.dll、vcruntime140.dll等。如果目标机器上没装 Visual C 运行库程序会启动失败并提示缺少 DLL。解决办法是在编译时选择静态链接运行库或者在目标机器上安装对应的运行库。我一般倾向于静态链接虽然生成的 exe 会大一些但分发起来省事。3.4 编译产物的验证与首次运行编译完成后先别急着双击运行。我建议在命令行里启动程序这样如果有报错信息可以直接看到。进入Release目录执行./ArmorPaint.exe如果程序正常启动会看到一个项目选择界面。这时候可以新建一个项目随便拖一个模型进去试试笔刷和图层功能是否正常。如果程序闪退或者黑屏先检查显卡驱动是不是最新的然后确认编译时选的图形后端和你的显卡是否匹配。比如有些老显卡对 Direct3D 11 支持不完整换成 OpenGL 后端可能就好了。首次运行还有一个常见问题是着色器编译失败。ArmorPaint 在启动时会编译一批着色器如果显卡驱动对某些 GLSL 或 HLSL 特性支持不好就会卡在这一步。解决办法是更新显卡驱动或者在编译时加上--shader-model参数指定较低的着色器模型版本。这个参数的具体用法可以在 Kha 的文档里查到。提示编译成功后建议把整个Release目录打包备份。这样以后换机器或者重装系统直接解压就能用不用重新走一遍编译流程。我一般会按日期命名备份文件夹比如armorpaint-build-20240601方便回溯。4. 编译版与官方版的差异及使用建议4.1 功能层面的对比编译版和官方付费版在核心功能上是一致的因为源码相同。但官方版会包含一些编译版没有的东西比如自动更新检查、官方预设材质库、以及某些平台特定的优化。我对比过几个版本发现官方版的启动速度略快一些可能是因为官方编译时启用了一些额外的优化选项。另一个差异是插件和扩展的支持。官方版内置了插件管理器可以一键安装社区开发的插件。编译版虽然也能手动安装插件但需要自己处理依赖和路径配置对新手来说门槛稍高。如果你重度依赖插件生态官方版会更省心。还有一点是授权和合规性。官方版购买后会得到一个许可证密钥用于激活软件。编译版没有这个密钥启动时可能会提示未授权但功能上不受影响。如果你只是个人学习使用编译版完全够用如果要用于商业项目建议还是购买官方版一方面是合规另一方面也能获得开发者的技术支持。4.2 性能与稳定性的实际表现我在同一台机器上对比过编译版和官方版的性能。用同一个模型、同一套笔刷操作帧率表现基本一致差异在误差范围内。稳定性方面编译版偶尔会遇到一些官方版没有的小问题比如某个特定操作导致崩溃或者导出某种格式时出错。这些问题通常是因为编译时的配置和官方版不完全一样比如优化级别、链接库版本等。不过编译版也有它的优势你可以自己修改源码定制一些官方版没有的功能。比如我改过笔刷的默认参数让它更符合我的使用习惯还改过导出面板的默认设置省去了每次手动调整的麻烦。这种灵活性是编译版独有的。如果你追求极致的稳定性建议用官方版如果你喜欢折腾、想深入学习软件内部机制编译版是更好的选择。我自己的做法是日常生产用官方版学习和实验用编译版。4.3 分发与使用的注意事项编译版可以自由分发但要注意几点。第一不要去掉源码中的版权声明和许可证信息这是 zlib 许可证的基本要求。第二分发时最好附上源码或者源码的获取方式方便接收者自行编译和修改。第三不要用编译版冒充官方版进行销售这不仅违反许可证精神也可能涉及法律风险。如果你把编译版分享给朋友建议同时提供一份简单的编译说明告诉他们你是怎么编译的、用了哪些版本的工具。这样对方遇到问题时可以对照排查也方便他们自己重新编译。我一般会写一个README放在压缩包里内容包括编译环境、工具版本、编译命令和已知问题。注意不同机器上编译出来的程序可能不通用。比如在 Intel 平台上编译的版本拿到 AMD 平台上可能因为指令集差异而无法运行。所以分发编译版时最好说明编译平台和配置或者直接提供源码让对方自己编译。5. 常见编译错误与排查方法实录5.1 依赖缺失类错误的快速定位编译过程中最常见的错误就是找不到某个头文件或库文件。这类错误的排查思路很直接看错误信息里提到的文件名然后确认这个文件属于哪个依赖再检查那个依赖是否安装正确。比如报错fatal error: GL/glew.h file not found说明 GLEW 库的开发文件没装。Windows 上可以通过 NuGet 或者手动下载 GLEW 的二进制包把头文件和库文件放到编译器能找到的目录。Linux 上用apt install libglew-dev就能解决。再比如报错undefined reference to XOpenDisplay说明 X11 的开发库没链接上。Linux 上安装libx11-dev然后在编译脚本里确认链接参数包含了-lX11。我整理了一个常见依赖缺失的对照表方便快速定位错误信息关键词缺失的依赖Windows 解决方案Linux 解决方案GL/glew.hGLEW下载 GLEW 二进制包并配置路径apt install libglew-devXOpenDisplayX11不适用apt install libx11-devd3d11.libDirect3D 11安装 Windows SDK不适用AL/al.hOpenAL下载 OpenAL SDKapt install libopenal-devpng.hlibpng下载 libpng 源码编译或找预编译包apt install libpng-dev5.2 版本不兼容导致的编译失败版本不兼容是另一个高频问题。Haxe 编译器、Kha 框架、ArmorPaint 源码三者之间有一个兼容矩阵任意一个版本对不上都可能导致编译失败。我遇到过最典型的情况是用 Haxe 4.3 编译时Kha 的某个宏函数报类型错误换成 Haxe 4.2.5 就正常了。排查这类问题的思路是先确认 ArmorPaint 源码的提交时间然后找那个时间点前后发布的 Haxe 和 Kha 版本。ArmorPaint 的 GitHub 提交记录里通常会写清楚更新了哪个依赖的版本顺着这条线索去找对应的版本号成功率会高很多。如果实在找不到确切的版本信息可以尝试用较老的稳定版。Haxe 4.2.x 系列和 Kha 的 2022 年左右的提交是我实测兼容性最好的组合。太新的版本往往引入了破坏性变更太老的版本又可能缺少 ArmorPaint 需要的某些特性。5.3 运行时崩溃与渲染异常的排查编译通过不代表程序就能正常运行。我遇到过编译成功但一启动就闪退的情况排查后发现是着色器编译失败导致的。这类问题的排查方法是在命令行启动程序观察输出日志。ArmorPaint 在启动时会打印一些调试信息如果着色器编译出错日志里会有对应的错误码和描述。另一个常见问题是渲染异常比如画面全黑、纹理显示错乱、笔刷轨迹偏移等。这些问题通常和显卡驱动或图形后端有关。先更新显卡驱动到最新版然后尝试切换图形后端。Windows 上 Direct3D 11 和 OpenGL 都试试看哪个更稳定。Linux 上如果用的是开源驱动可以试试专有驱动反之亦然。还有一种情况是程序能运行但某些功能不可用比如导出功能报错、图层混合模式异常等。这类问题往往和编译时的配置有关比如某些可选功能没启用。检查make.js里的编译参数确认没有漏掉必要的选项。ArmorPaint 的文档里会列出所有可用的编译参数对照检查一遍通常能找到原因。提示如果遇到难以定位的崩溃可以尝试用 Debug 配置编译一版然后在 Visual Studio 里附加调试器运行。这样崩溃时能看到完整的调用栈比看日志高效得多。虽然 Debug 版运行慢但排查问题时非常有用。5.4 编译环境清理与重新编译有时候编译失败是因为之前的中间产物残留导致的。比如修改了编译参数后旧的.obj文件和新的源码不匹配链接时就会报奇怪的错误。这时候需要清理编译目录重新生成项目文件再编译。清理的方法是删除armorpaint/build目录下的所有内容然后重新执行make.js生成项目文件。如果问题依旧可以进一步删除 Kha 的编译缓存通常在kha/build或者用户目录下的某个缓存文件夹里。我一般会写一个简单的清理脚本把相关目录一次性删干净省得手动找。重新编译时建议把编译日志保存下来方便对比。比如node make.js --graphics direct3d11 --compile build.log 21这样所有输出都会写到build.log里出错时可以搜索关键词快速定位。我习惯在日志里搜error和warning先看错误再看警告很多时候警告里就藏着问题的线索。6. 我在这几次编译中攒下的经验编译 ArmorPaint 这件事说难不难说简单也不简单。第一次编译我花了整整三天大部分时间都耗在版本匹配和依赖处理上。后来摸清了套路现在从零开始到编译成功大概两个小时就能搞定。这中间积累的一些经验我觉得比官方文档里写的更有参考价值。第一个经验是不要追求最新版本。不管是 Haxe、Kha 还是 Visual Studio用 ArmorPaint 源码发布时对应的那个版本最稳妥。新版本往往引入了不兼容的变更而 ArmorPaint 的更新频率没那么高跟不上最新工具链的节奏。我现在的做法是编译前先看 ArmorPaint 最近一次更新依赖是什么时候然后去找那个时间点的工具版本。第二个经验是把编译过程脚本化。我写了一个批处理脚本把拉取源码、切换版本、安装依赖、执行编译这些步骤都串起来。这样下次换机器或者重新编译时一条命令就能跑完不用再手动一步步操作。脚本里还可以加上错误检查比如某个命令失败了就停下来提示避免错误累积到最后才被发现。第三个经验是多备份编译产物。每次编译成功后我都会把整个输出目录打包备份并且记录下这次编译用的工具版本和参数。这样以后遇到问题时可以快速回退到已知可用的版本而不是从头再编译一遍。我现在的备份文件夹里存了五六个不同时期编译的版本有时候某个版本在特定场景下表现更好就能直接拿来用。第四个经验是加入社区。ArmorPaint 的论坛和 Discord 频道里有很多同样在折腾编译的人遇到问题时去搜一搜或者问一问往往能省下大量时间。我遇到过一个着色器编译失败的问题自己排查了两天没结果在社区里一问有人指出是显卡驱动的一个已知 bug换个驱动版本就解决了。这种信息在官方文档里是找不到的。最后再分享一个小技巧如果你只是想在特定平台上做一点小修改不一定要完整编译整个项目。ArmorPaint 支持通过插件系统加载外部脚本有些定制化需求用插件就能实现不用动源码。比如修改界面主题、添加自定义笔刷预设这些都可以通过插件完成。只有涉及到核心逻辑的改动才需要重新编译。这样能省下不少时间和精力。