企业官网建设流程全解析

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

ArmorPaint 这个软件，圈子里做 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或opengl，Linux 上通常用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 上，我习惯用命令行调用 MSBuild：

msbuild armorpaint.sln /p:Configuration=Release /p:Platform=x64

用 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。

我整理了一个常见依赖缺失的对照表，方便快速定位：

5.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 2>&1

这样所有输出都会写到build.log里，出错时可以搜索关键词快速定位。我习惯在日志里搜error和warning，先看错误，再看警告，很多时候警告里就藏着问题的线索。

6. 我在这几次编译中攒下的经验

编译 ArmorPaint 这件事，说难不难，说简单也不简单。第一次编译我花了整整三天，大部分时间都耗在版本匹配和依赖处理上。后来摸清了套路，现在从零开始到编译成功，大概两个小时就能搞定。这中间积累的一些经验，我觉得比官方文档里写的更有参考价值。

第一个经验是：不要追求最新版本。不管是 Haxe、Kha 还是 Visual Studio，用 ArmorPaint 源码发布时对应的那个版本最稳妥。新版本往往引入了不兼容的变更，而 ArmorPaint 的更新频率没那么高，跟不上最新工具链的节奏。我现在的做法是，编译前先看 ArmorPaint 最近一次更新依赖是什么时候，然后去找那个时间点的工具版本。

第二个经验是：把编译过程脚本化。我写了一个批处理脚本，把拉取源码、切换版本、安装依赖、执行编译这些步骤都串起来。这样下次换机器或者重新编译时，一条命令就能跑完，不用再手动一步步操作。脚本里还可以加上错误检查，比如某个命令失败了就停下来提示，避免错误累积到最后才被发现。

第三个经验是：多备份编译产物。每次编译成功后，我都会把整个输出目录打包备份，并且记录下这次编译用的工具版本和参数。这样以后遇到问题时，可以快速回退到已知可用的版本，而不是从头再编译一遍。我现在的备份文件夹里存了五六个不同时期编译的版本，有时候某个版本在特定场景下表现更好，就能直接拿来用。

第四个经验是：加入社区。ArmorPaint 的论坛和 Discord 频道里有很多同样在折腾编译的人，遇到问题时去搜一搜或者问一问，往往能省下大量时间。我遇到过一个着色器编译失败的问题，自己排查了两天没结果，在社区里一问，有人指出是显卡驱动的一个已知 bug，换个驱动版本就解决了。这种信息在官方文档里是找不到的。

最后再分享一个小技巧：如果你只是想在特定平台上做一点小修改，不一定要完整编译整个项目。ArmorPaint 支持通过插件系统加载外部脚本，有些定制化需求用插件就能实现，不用动源码。比如修改界面主题、添加自定义笔刷预设，这些都可以通过插件完成。只有涉及到核心逻辑的改动，才需要重新编译。这样能省下不少时间和精力。