1. 为什么我要自己编译 ArmorPaintArmorPaint 这个软件圈子里做 3D 纹理绘制的人应该都不陌生。它是一款开源的 3D 模型纹理绘制工具定位上跟 Substance Painter 属于同一赛道支持 PBR 材质流程能直接在 3D 模型表面进行图层化绘制而且底层用的是 GPU 加速渲染实时反馈相当跟手。官方提供的是付费的预编译版本源码则托管在公开仓库里采用比较特殊的授权模式——源码开放但官方编译好的二进制包需要付费购买。这就意味着如果你不想花钱或者想自己改点东西那就得自己动手从源码编译。我这次折腾编译版起因其实挺简单手头有几台不同配置的机器官方付费版按人头授权多设备切换用起来别扭再加上我平时喜欢改一些 UI 细节和快捷键映射用官方包每次更新都得重新适应。索性花了两天时间把编译流程彻底跑通顺便把踩过的坑都记下来。这篇文章就是把我从零开始编译 ArmorPaint 的完整过程、关键参数、依赖处理、常见报错和解决方案全部摊开讲清楚让你少走弯路。先说清楚这篇文章适合谁看一是有一定命令行基础、想自己编译 ArmorPaint 但被依赖和工具链卡住的人二是编译过程中遇到各种报错、找不到北的人三是想了解一个典型 GPU 渲染类桌面应用从源码到可执行文件完整构建流程的人。如果你完全没碰过命令行那这篇文章可能会有点吃力但我会尽量把每一步都写细关键命令直接给出来你照着敲基本能跑通。ArmorPaint 的编译版和官方付费版在功能上是一致的区别主要在于编译版需要你自己处理依赖、自己配置构建环境而且不同平台的编译难度差异很大。Windows 平台相对友好Linux 平台依赖多一些但社区支持好macOS 平台因为图形 API 的差异坑最多。我这次主要在 Windows 和 Linux 两个平台上做了完整验证macOS 部分我会提到已知的问题和绕行方案但不作为主线。2. 编译前的整体思路与环境选型2.1 为什么选择源码编译而不是直接下载很多人第一反应是既然官方有付费版为什么不直接买这个问题我认真想过。官方付费版确实省事下载即用自动更新省去了所有编译烦恼。但源码编译有几个官方版给不了的好处。第一是完全可控你可以自己决定用哪个版本的依赖库可以针对自己的硬件做编译优化比如开启特定的 CPU 指令集或者调整 GPU 后端。第二是可修改ArmorPaint 的 UI 层和部分逻辑层是开放的你可以改快捷键、改界面布局、甚至加自己的小工具。第三是学习价值整个编译过程涉及 CMake 构建系统、GPU 图形库链接、跨平台工具链配置这些经验在别的项目里也能复用。当然代价也很明显编译一次可能要折腾几个小时甚至几天遇到依赖版本不匹配、链接错误、运行时崩溃都是家常便饭。所以我的建议是如果你只是想用这个软件画画纹理不想折腾那官方付费版是更理性的选择。如果你跟我一样享受折腾的过程或者确实有定制需求那继续往下看。2.2 编译 ArmorPaint 需要哪些核心依赖ArmorPaint 的构建依赖可以分成几大类我按重要程度排一下构建工具链CMake3.15 以上、Git、对应平台的 C/C 编译器Windows 上是 MSVC 或 MinGWLinux 上是 GCC/Clang。图形与窗口库这是最核心也最容易出问题的部分。ArmorPaint 底层用的是 Kha 框架Kha 又依赖各平台的图形 API。Windows 上主要走 Direct3D 11/12 或者 VulkanLinux 上走 OpenGL 或 Vulkan。你需要确保显卡驱动支持对应的 API 版本。音频与输入库虽然纹理绘制对音频要求不高但 Kha 框架会链接音频后端缺少相关库会导致链接失败。Node.js 与相关工具Kha 的构建流程里有一部分是用 Node.js 脚本驱动的用来生成项目文件和资源编译。这个很多人会忽略结果卡在第一步。Python部分辅助脚本需要 Python 环境建议用 Python 3.8 以上。我实测下来最稳妥的组合是Windows 10/11 Visual Studio 2022 CMake 3.24 Node.js 18 LTS Python 3.10。Linux 这边用 Ubuntu 22.04 GCC 11 CMake 3.22 Node.js 18基本能顺利跑通。2.3 不同平台的编译难度对比为了让你心里有数我把三个主流平台的情况列个表平台编译难度主要坑点推荐指数Windows中等依赖库路径配置、MSVC 版本匹配、DirectX SDK高Linux中等偏低系统库版本冲突、显卡驱动、权限问题高macOS高Metal 后端支持不完整、Xcode 版本敏感、签名问题低Windows 的坑主要集中在环境配置上一旦配好就很稳。Linux 的坑在于系统自带的库版本可能和项目要求的不一致需要手动指定。macOS 则是先天不足ArmorPaint 在 macOS 上的支持一直不算完善编译出来能跑但性能一般而且每次系统更新都可能出问题。提示如果你是第一次编译强烈建议从 Linux 开始社区文档最全报错信息也最容易搜到解决方案。Windows 次之。macOS 除非你特别熟悉 Xcode 工具链否则不建议作为首次尝试平台。3. 核心细节解析与实操要点3.1 源码获取与目录结构说明第一步是把源码拉下来。ArmorPaint 的源码仓库在公开的代码托管平台上直接克隆就行git clone --recursive https://github.com/armory3d/armorpaint.git cd armorpaint注意--recursive这个参数因为 ArmorPaint 依赖了多个子模块包括 Kha 框架本身、一些第三方库等。如果你忘了加这个参数后面构建时会报找不到子模块的错误。如果已经克隆了但没加可以补一句git submodule update --init --recursive拉下来之后目录结构大致是这样的Sources/ArmorPaint 自己的核心源码包括 UI、绘制逻辑、材质系统等。Kha/子模块图形框架负责窗口创建、GPU 渲染、输入处理。Libraries/第三方依赖库比如数学库、图像处理库等。Assets/默认资源包括着色器、图标、预设材质。make.js或类似的构建脚本Kha 框架的构建入口。理解这个结构很重要因为后面报错时你需要知道是哪个部分出了问题。比如着色器编译错误通常出在Assets/下的着色器文件链接错误多半是Libraries/里的库版本不对。3.2 构建工具链的安装与版本选择Windows 上我推荐用 Visual Studio 2022 社区版安装时记得勾选“使用 C 的桌面开发”工作负载里面包含了 MSVC 编译器和 Windows SDK。CMake 建议单独安装最新版不要用 VS 自带的那个版本可能偏旧。Node.js 装 LTS 版本就行安装时勾选“添加到 PATH”。Linux 上就简单很多一条命令搞定大部分sudo apt update sudo apt install build-essential cmake git nodejs npm python3 python3-pip但要注意Ubuntu 22.04 自带的 CMake 是 3.22够用。Node.js 自带的版本可能偏旧建议用 NodeSource 的源装 18 LTS。显卡驱动方面NVIDIA 用户装好官方驱动AMD 和 Intel 用户用开源的 Mesa 驱动就行但要确保支持 OpenGL 4.5 或 Vulkan 1.2。注意Node.js 的版本很关键。我试过用 Node.js 20 编译结果 Kha 的构建脚本报了一堆语法错误换回 18 LTS 就正常了。所以别盲目追新用 LTS 版本最稳。3.3 图形后端的选择与配置ArmorPaint 支持多种图形后端编译时可以通过参数指定。Windows 上默认走 Direct3D 11Linux 上默认走 OpenGL。如果你想用 Vulkan需要在构建时显式开启。我的建议是除非你有明确需求否则就用默认后端兼容性最好。如果你确实想用 Vulkan构建命令里要加对应的标志。具体怎么加后面实操部分我会详细说。这里先解释一下为什么图形后端这么重要ArmorPaint 的所有绘制操作都是在 GPU 上完成的着色器代码需要编译成对应后端的格式。Direct3D 用的是 HLSLOpenGL 和 Vulkan 用的是 GLSL/SPIR-V。如果后端选错了着色器编译就会失败软件根本启动不了。3.4 依赖库的版本匹配问题这是编译过程中最容易翻车的地方。ArmorPaint 依赖的一些第三方库对版本很敏感比如某个图像处理库用新版本编译能过但运行时崩溃用旧版本反而稳定。我踩过的坑包括某个数学库的 API 在新版本里改了签名导致编译报错。某个压缩库的 ABI 不兼容链接时提示符号找不到。系统自带的库版本和项目要求的版本不一致需要手动指定路径。解决这类问题的通用思路是先看项目根目录下有没有README或者BUILDING之类的文档里面通常会写明推荐的依赖版本。如果没有就去项目的 issue 区搜相关报错大概率有人遇到过。再不行就逐个尝试相邻的版本用二分法定位能用的版本。4. 完整编译流程与关键步骤实现4.1 Windows 平台编译实录先说 Windows因为用的人最多。我这次用的是 Windows 11 VS2022 CMake 3.24 Node.js 18。第一步打开“x64 Native Tools Command Prompt for VS 2022”注意一定要用这个专用命令行它会自动配置好 MSVC 的环境变量。普通的 cmd 或 PowerShell 不行。第二步进入源码目录先跑一遍 Kha 的构建脚本生成项目文件node make.js这个命令会读取khafile.js里的配置生成对应后端的项目文件。如果这一步报错多半是 Node.js 版本问题或者子模块没拉全。第三步用 CMake 生成 VS 解决方案mkdir build cd build cmake .. -G Visual Studio 17 2022 -A x64这里-G指定生成器-A指定架构。如果你用的是其他版本的 VS生成器名称要相应调整。第四步编译cmake --build . --config Release这一步会花比较长时间取决于你的 CPU。编译完成后可执行文件在build/Release/目录下。我实测下来Windows 上最容易出的问题是 DirectX SDK 找不到。虽然 Windows SDK 里已经包含了大部分 DirectX 组件但某些旧版的头文件可能缺失。解决办法是装一个独立的 DirectX SDK或者手动指定 Windows SDK 的版本。4.2 Linux 平台编译实录Linux 这边我用的是 Ubuntu 22.04流程略有不同。第一步装依赖sudo apt install libgl1-mesa-dev libglu1-mesa-dev libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libasound2-dev这些是图形和音频相关的基础库缺一个都可能导致链接失败。第二步生成项目文件node make.js第三步用 CMake 构建mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j$(nproc)-j$(nproc)是并行编译能大幅缩短时间。我这边 8 核的机器大概编译了 15 分钟。Linux 上我遇到的主要问题是显卡驱动。我的一台老机器用的是 Intel 核显Mesa 驱动版本偏旧不支持 OpenGL 4.5导致编译能过但运行时报错。升级 Mesa 到最新版后解决。所以如果你在 Linux 上编译先确认你的显卡驱动支持 OpenGL 4.5 或 Vulkan 1.2。4.3 编译参数调优与性能取舍默认的 Release 编译已经开了-O2优化但如果你想进一步压榨性能可以手动加一些标志。比如在 CMake 配置时加cmake .. -DCMAKE_BUILD_TYPERelease -DCMAKE_CXX_FLAGS-O3 -marchnative-O3是最高级别的优化-marchnative会让编译器针对你当前的 CPU 架构生成最优指令集。但要注意-marchnative编译出来的二进制文件不能在其他 CPU 上运行如果你要分发给别人就别加这个。另一个可以调的是图形后端。如果你想强制用 Vulkan在make.js执行前设置环境变量export KHA_BACKENDVulkan node make.js或者在 Windows 上set KHA_BACKENDVulkan node make.js但 Vulkan 后端在某些老显卡上可能不稳定建议先用默认后端跑通再尝试切换。4.4 编译产物的验证与运行测试编译完成后别急着高兴先做几项验证。第一检查可执行文件是否生成。Windows 上在build/Release/ArmorPaint.exeLinux 上在build/Deploy/ArmorPaint或类似路径。第二直接运行看能否正常启动。如果闪退多半是着色器编译失败或者图形后端不兼容。这时候可以在命令行里运行看具体的错误输出。第三加载一个测试模型画几笔看实时反馈是否正常。如果卡顿严重可能是 GPU 后端没选对或者驱动有问题。第四检查导出功能。ArmorPaint 支持导出纹理贴图随便画点东西导出成 PNG看文件是否正常生成。我这边第一次编译出来的版本启动就崩报的是着色器编译错误。后来发现是Assets/目录下的着色器文件没有正确复制到输出目录。手动复制过去就好了。这个问题在 Linux 上尤其常见因为构建脚本的路径处理有时候会出问题。5. 常见报错与排查技巧实录5.1 编译阶段典型报错与解决编译阶段的报错五花八门我挑几个最常见的说说。报错一找不到子模块fatal error: kha/Kha.h file not found这个就是子模块没拉全。解决办法git submodule update --init --recursive报错二CMake 找不到某个库Could NOT find OpenGL (missing: OPENGL_gl_LIBRARY)Linux 上装libgl1-mesa-devWindows 上确保 Windows SDK 装全了。报错三Node.js 脚本报语法错误SyntaxError: Unexpected token ?这是 Node.js 版本太新或太旧导致的。换 18 LTS 版本。报错四链接时符号未定义undefined reference to png_create_read_struct缺少某个第三方库或者库的版本不对。检查Libraries/目录下的库是否完整必要时手动编译安装。5.2 运行阶段崩溃与黑屏问题运行阶段的问题更棘手因为报错信息往往不明确。问题一启动即崩溃无任何提示多半是着色器编译失败。解决办法是查看日志文件通常在用户目录下的.armorpaint/文件夹里。日志里会写着色器编译的具体错误。问题二窗口打开但黑屏图形后端不兼容。尝试切换后端比如从 Direct3D 切到 Vulkan或者反过来。问题三界面正常但绘制无反应GPU 驱动问题。更新显卡驱动到最新版或者换一台机器试试。问题四导出纹理时崩溃内存不足或者图像库版本问题。检查导出分辨率是否过高降低分辨率试试。5.3 依赖冲突的排查思路依赖冲突是最难搞的一类问题因为报错信息往往指向不明。我的排查思路是这样的第一步确认所有依赖库的版本。用lddLinux或dumpbin /dependentsWindows查看可执行文件依赖了哪些库以及这些库的实际路径。第二步对比项目要求的版本和系统实际版本。如果差异较大就手动编译安装指定版本。第三步用LD_LIBRARY_PATHLinux或PATHWindows强制指定库的搜索路径确保加载的是正确版本。第四步如果还是不行就用静态链接的方式把依赖库直接编进可执行文件避免运行时查找。5.4 常见问题速查表问题现象可能原因解决方法编译报找不到头文件子模块未拉全执行git submodule update --init --recursiveCMake 配置失败缺少系统库安装对应的 dev 包Node.js 脚本报错Node 版本不匹配换 18 LTS链接符号未定义第三方库版本不对手动编译指定版本启动崩溃着色器编译失败检查日志确认资源文件路径黑屏图形后端不兼容切换后端绘制卡顿GPU 驱动旧更新驱动导出崩溃内存不足降低分辨率提示遇到任何报错第一件事是看日志。ArmorPaint 的日志文件里信息很全比控制台输出详细得多。养成看日志的习惯能省下大量搜索时间。6. 编译版的使用心得与后续扩展6.1 编译版和官方版的体验差异用了一段时间编译版说几点真实感受。启动速度上编译版和官方版差别不大因为核心代码是一样的。但在某些特定硬件上编译版因为可以针对 CPU 做优化反而略快一点。稳定性方面官方版经过更多测试确实更稳编译版偶尔会遇到一些奇怪的崩溃但重启后基本能恢复。功能上编译版可以自己改快捷键、改界面配色、甚至加一些官方版没有的小功能。比如我把画笔的默认大小调大了把常用的几个材质预设放到了更顺手的位置。这些改动虽然小但用起来很舒服。6.2 如何自定义编译选项如果你想改 UI 或者加功能需要动Sources/目录下的代码。ArmorPaint 的 UI 层用的是 Haxe 语言写的改起来不算难但需要一点学习成本。改完之后重新跑node make.js和 CMake 构建就行。一个常见的自定义需求是改默认快捷键。快捷键的定义在Sources/下的某个配置文件里找到对应的键值对改成你想要的就行。改完重新编译生效。另一个需求是改默认材质库。ArmorPaint 自带了一些预设材质你可以把自己的材质加进去编译时一起打包。这样每次启动就能直接用。6.3 编译版分发的注意事项如果你想把编译版分享给别人有几点要注意。第一-marchnative编译出来的版本不能随便分发因为别人的 CPU 可能不支持那些指令集。第二Windows 上分发时需要把依赖的 DLL 一起打包否则别人运行会报缺库。第三Linux 上不同发行版的库版本差异很大最好提供静态链接版本或者说明依赖要求。我个人的做法是自己用的版本开-marchnative分发给别人的版本用默认优化并且把依赖库都打包进去。这样虽然文件大一点但兼容性最好。6.4 后续可以尝试的扩展方向编译版跑通之后可以尝试一些更有意思的扩展。比如把 ArmorPaint 的绘制核心抽出来集成到自己的管线里或者写一个插件自动从参考图生成材质再或者针对特定类型的模型做优化比如只支持某种拓扑结构的网格。这些扩展都需要对源码有比较深的理解但编译版给了你这个可能性。官方版虽然也能通过脚本扩展但底层的东西改不了。编译版就没有这个限制你想改哪里就改哪里。最后分享一个小技巧编译之前先把源码打个 tag 或者记下 commit hash这样万一改崩了可以快速回滚。我一开始没注意这个改了一堆东西之后编译不过又忘了改了什么只能重新克隆一遍浪费了不少时间。后来养成习惯每次大改之前先 commit 一下出问题就 reset效率高很多。