企业官网建设流程全解析

• 游戏开发
• 图形学

本指南以 openage 仓库中的 doc/build_instructions/windows_msvc.md 为核心，系统梳理在 Microsoft Windows（x64/x86）下使用 Visual Studio MSVC 工具链编译 openage 的完整流程。由于 Windows 没有原生包管理器，openage 采用「手动安装工具链 + pip 安装 Python 依赖 + vcpkg 安装 C/C++ 库」的混合方式，本文从零开始覆盖环境搭建、配置、编译、开发模式运行以及 NSIS 安装包/便携版 7z 的打包发布，并结合仓库中的构建脚本（buildsystem/scripts/EmbedWinDependencies.cmake、packaging/CMakeLists.txt 等）解释每一步背后的实现原理。读完本文，你将能够在 Windows 上独立完成 openage 的构建、调试与交付。

1. 准备工作：理解 openage 的构建架构

openage 是一个开源的《帝国时代 II》引擎克隆项目。从构建角度看，它由两大部分组成（详见 doc/building.md）：

• libopenage：纯 C++ 核心库，负责渲染、音频、事件系统、路径寻路等引擎底层；
• openage：Python 包，提供游戏逻辑、转换器、测试等上层功能，其中部分模块通过 Cython 编译为 C 扩展与 C++ 库互操作。

整个项目统一使用CMake驱动构建（仓库还提供了一个可选的configure包装脚本，Windows 上直接使用原生 CMake 命令即可）。构建过程涉及 Cython 扩展编译、代码生成等环节，因此对工具链的版本与位数（32/64 位）要求严格。

关键前提：位数必须全程一致。如果打算构建 64 位（x64）版本，那么 Python、vcpkg 库以及 CMake 生成的 Visual Studio 工程都必须是 x64；反之亦然。混用位数是 Windows 构建最常见的失败原因。

2. 安装构建工具链（手动安装部分）

Windows 没有统一的包管理器，因此以下三个工具需要手动下载安装。如果你已装有最新稳定版本，可以跳过对应步骤。

2.1 Visual Studio Build Tools

• 下载并安装Visual Studio Build Tools（vs_BuildTools.exe），勾选「Visual C++ Buildtools」工作负载。这是 MSVC 编译器、头文件与链接器的来源。
• 若你希望获得 IDE 开发体验，openage 文档也提供了多种 IDE 的使用指引，可参考 doc/ide/README.md，其中包含 Qt Creator、VSCode、Emacs 等环境的配置建议。

2.2 Python 3

• 从 Python 官网下载 Windows 安装包安装Python 3，安装时需要开启以下选项：
  • pip：后续依赖均通过pip安装；
  • Precompile standard library（预编译标准库）；
  • Download debug binaries（下载调试二进制）。
  • 如果安装时遗漏，可重新运行安装程序并选择Modify补齐。
• 位数要求：构建 x64 版 openage 必须使用 64 位 Python，反之亦然。

2.3 CMake

• 安装CMake（仓库要求版本 >= 3.16，见 doc/building.md 的依赖清单）。CMake 将生成 Visual Studio 工程文件并驱动整个构建。

2.4 nyan 的 Windows 依赖

openage 依赖引擎配置语言nyan（见 doc/building.md 中 "nyan installation" 一节）。在 Windows 上构建 nyan 主要需要flex（win_flex/win_bison，即win_flex.exe）。nyan 可以通过两种方式提供：

1. 手动克隆 nyan 仓库并按其 Windows 构建说明编译，CMake 会通过用户包注册表（~/.cmake/packages/nyan/）自动发现；
2. 让 openage 自动下载并构建 nyan：在 CMake 配置阶段传入-DDOWNLOAD_NYAN=YES与-DFLEX_EXECUTABLE=<path to win_flex.exe>（详见下文第 5 节）。

3. 安装 Python 模块

在<Python 3 installation directory>\Scripts目录下打开命令行，执行：

pip install cython numpy lz4 toml pillow pygments pyreadline3 mako

各模块在 openage 构建体系中的用途（可对照 doc/building.md 的依赖表）：

注意事项：

• 请确保你安装这些模块所针对的 Python 实例，正是 CMD 中python命令实际指向的那个实例；
• 同时确保python与python3两个命令指向同一个且相同版本的 Python 3，避免 CMake/Cython 探测到不一致的解释器。

4. 通过 vcpkg 安装 C/C++ 依赖

vcpkg 是微软开源的 C/C++ 包管理器，openage 在 Windows 上用它集中管理原生库依赖。首先按 vcpkg 官方快速入门完成 vcpkg 本身的搭建，然后在<vcpkg directory>下打开命令行，执行：

vcpkg install dirent eigen3 fontconfig freetype harfbuzz libepoxy libogg libpng opus opusfile qtbase qtdeclarative qtmultimedia toml11

这些包与 openage 依赖表的对应关系：

• eigen3：线性代数库（CR，>=3）；
• freetype / harfbuzz / fontconfig：字体渲染与字体配置（CR）；
• libepoxy：OpenGL 函数指针加载库（CR，OpenGL >=3.3 由它承载）；
• libpng：PNG 图像解码（CR）；
• libogg / opus / opusfile：音频解码与播放（CRA）；
• qtbase / qtdeclarative / qtmultimedia：Qt6（>=6.2）的 Core、Quick、QuickControls、Multimedia 模块，用于 QML 图形界面（CR）；
• toml11：C++ 侧的 TOML 配置解析（CR）；
• dirent：Windows 上提供 POSIX 风格目录遍历接口（openage 在 Windows 下适配所用）。

如果还需要Vulkan 图形支持（可选依赖，见 doc/building.md 中标记O的 vulkan），追加执行：

vcpkg install vulkan

关于 Qt 的两种方案：vcpkg 的qt端口已拆分为多个包，编译时间已可接受；若你更希望使用Qt 官方预编译版本，可以跳过上述qt*包，改用 Qt 官方在线安装器，并在后续 CMake 配置命令中附加-DCMAKE_PREFIX_PATH=<QT6 directory>。

关于 x64 库：构建 64 位版本时，vcpkg 默认的 triplet 是 x86（32 位），必须让 vcpkg 编译 64 位库。两种做法任选其一：

• 在上述安装命令后追加--triplet x64-windows；
• 或设置环境变量VCPKG_DEFAULT_TRIPLET=x64-windows。

该 triplet 会直接决定后续 CMake 从installed\<triplet>\bin、installed\<triplet>\tools等目录取用库文件，务必与目标架构一致。

5. 配置并构建 openage

当前 openage 尚不支持完全脱离源码目录的 out-of-source 构建，但官方流程仍然使用独立的build目录来存放编译产物。在<openage directory>下打开命令行：

mkdir build cd build cmake -DCMAKE_TOOLCHAIN_FILE=<vcpkg directory>\scripts\buildsystems\vcpkg.cmake .. cmake --build . --config RelWithDebInfo -- /nologo /m /v:m

各参数含义：

• -DCMAKE_TOOLCHAIN_FILE=...\vcpkg.cmake：告知 CMake 通过 vcpkg 工具链文件解析依赖，构建系统会据此定位installed目录；
• --config RelWithDebInfo：选择 Release 带调试信息的配置（构建脚本与打包脚本默认都以该配置为准）；
• /nologo /m /v:m：MSBuild 参数——隐藏横幅、多进程并行编译、中等详细度输出。

5.1 架构与生成器选项

如果构建 x64 版本，需要在第一条 cmake 命令中显式指定生成器与架构（以 VS2022 为例）：

cmake -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=<vcpkg directory>\scripts\buildsystems\vcpkg.cmake ..

-A x64与上文中 Python 位数、vcpkg 的x64-windowstriplet 必须三处一致。

5.2 自动下载 nyan

若希望 CMake 自动下载并构建 nyan，则在第一条 cmake 命令中追加：

-DDOWNLOAD_NYAN=YES -DFLEX_EXECUTABLE=<path to win_flex.exe>

这对应 doc/building.md 中描述的-DDOWNLOAD_NYAN=YES机制：openage 会自动获取 nyan 源码、使用win_flex.exe生成词法分析器并完成编译，从而省去手动克隆 nyan 仓库的步骤。

5.3 构建产物结构

构建完成后，核心产物包括：

• <openage directory>\build\libopenage\<config built>\openage.dll：C++ 核心库的 DLL；
• <openage directory>\build\run.exe：游戏启动器可执行文件；
• nyan.dll：nyan 库，其位置取决于你获取 nyan 的方式（手动构建的安装目录或自动下载的构建目录）。

6. 在开发模式（devmode）下运行 openage

Windows 上运行 openage 比其他平台多出若干环境准备步骤，逐项说明如下。

6.1 安装 DejaVu Serif 字体

openage 需要DejaVu Book Font系列中的 Serif 字体渲染界面文字：

1. 下载并解压最新的dejaVu-fonts-ttf压缩包；
2. 选中其中全部ttf\DejaVuSerif*.ttf文件，右键选择「为所有用户安装」（需要管理员权限）。

6.2 配置 fontconfig

安装字体后还需让 fontconfig 找到字体配置：

• 将环境变量FONTCONFIG_PATH设置为：
  • <vcpkg directory>\installed\<relevant config>\tools\fontconfig\fonts\，或
  • <vcpkg directory>\installed\<relevant config>\etc\fonts\（<relevant config>即目标 triplet，如x64-windows）；
• 将fontconfig\57-dejavu-serif.conf复制到%FONTCONFIG_PATH%\conf.d目录下。

从源码看，vcpkg 安装的 fontconfig 字体目录会被构建系统直接复用：在 buildsystem/scripts/EmbedWinDependencies.cmake 中，打包阶段会把<vcpkg_dir>/tools/fontconfig/fonts整体复制到 Python 安装前缀目录，保证运行时字体配置可用。

6.3 （可选）设置 AGE2DIR

设置环境变量AGE2DIR指向《帝国时代 II》的安装目录。openage 需要原始游戏资产才能进行资源转换与运行，AGE2DIR用于帮助它定位这些资产。

6.4 设置 QML2_IMPORT_PATH

openage 的图形界面基于 Qt6 QML（界面定义见 assets/qml，如main.qml、IngameHud.qml等）。需要让 Qt 的 QML 导入系统找到模块路径：

• vcpkg 安装 Qt 时：<vcpkg directory>\installed\<relevant config>\qml；
• 预编译 Qt 时：<qt directory>\<qt-version>\<compiler-version>\qml。

6.5 确认运行时 DLL

openage 运行需要以下 DLL：

• openage.dll：通常位于<openage directory>\build\libopenage\<config built>；
• nyan.dll：位置取决于获取 nyan 的方式；
• vcpkg 依赖库的 DLL：正常情况下构建过程会自动将它们复制到<openage directory>\build\libopenage\<config built>；若未自动复制，可到<vcpkg directory>\installed\<relevant config>\bin手工拷贝；
• 若使用了 Qt 官方预编译版，Qt6 的 DLL 位于<QT6 directory>\bin。

底层机制：DLL 的自动收集由 buildsystem/scripts/EmbedWinDependencies.cmake 完成。该脚本调用dumpbin /DEPENDENTS递归解析每个二进制文件的依赖 DLL，从<vcpkg_dir>/bin复制缺失项（见 L21-L42）；同时针对 Qt，还会调用windeployqt部署 QML 插件与库（见 L45-L65），并调用 vcpkg 的applocal.ps1做应用本地化拷贝。因此大多数情况下你无需手动处理 DLL。

6.6 启动游戏

完成上述准备后：

1. 在<openage directory>\build\下打开一个 CMD 窗口，首次运行执行：

   python -m openage main

   这会完成资源转换等初始化流程并进入游戏主界面；

2. 之后每次启动直接执行：

   <openage directory>\build\run.exe

打包安装场景下，buildsystem/templates/openage.bat.in 提供了等价入口：它设置PATH、XDG_DATA_HOME后调用python.exe -m openage，而 buildsystem/templates/qt.conf 则在打包时被复制到 Python 目录，将 Qt 插件与 QML 导入路径指向..\bin\plugins与..\bin\qml。

7. 打包发布：生成 NSIS 安装包与便携 7z

openage 的 Windows 打包由 CPack 驱动，支持两种产物：NSIS 安装包（openage-<version>-<arch>-installer.exe）与便携 7z 压缩包（openage-<version>-<arch>-portable.7z），生成器配置见 packaging/CMakeLists.txt。

7.1 安装 NSIS

• 安装NSIS（Nullsoft Scriptable Install System），它是 CPack 的 NSIS 生成器所依赖的外部程序。

7.2 按 Qt 来源调整 windeployqt 开关

根据 Qt 的获取方式，编辑<openage-repo-dir>\buildsystem\templates\ForwardVariables.cmake.in中的一行：

# Use windeploy for packaging qt-prebuilt, standard value '1' for windeploy, '0' for vcpkg set(use_windeployqt 1)

• 使用Qt 预编译版：保持1（构建系统将调用windeployqt部署 Qt 运行库，见 EmbedWinDependencies.cmake 中if(use_windeployqt AND windeployqt)分支）；
• 使用vcpkg 安装的 Qt：改为0，此时 DLL 收集完全依赖dumpbin递归解析与applocal.ps1（见 EmbedWinDependencies.cmake）。

该文件由 packaging/CMakeLists.txt 在配置期通过configure_file生成并注册为安装脚本，因此修改后需要重新运行 CMake 配置。

7.3 执行打包

在<openage directory>\build下打开命令行（或沿用构建步骤中的窗口）：

cpack -C RelWithDebInfo

• 打包会比较耗时，追加-V可输出详细日志，便于观察各依赖的收集过程；
• 安装包文件名为openage-<version>-<arch>.exe，其中<arch>由环境变量TARGET_PLATFORM控制（例如amd64、x86），见 packaging/CPackOptions.cmake；
• 若设置了环境变量IS_NIGHTLY，文件名中会追加_NIGHTLY后缀并采用完整版本字符串（见 CPackOptions.cmake）；
• NSIS 相关行为（包名、卸载前先卸载旧版、修改 PATH 策略等）同样定义在 CPackOptions.cmake 中，可在打包前按需调整。

8. 常见问题与排查

结合 doc/building.md 的 Troubleshooting 部分，Windows 构建中常见的问题包括：

• CMake 找不到 Qt/Python 等组件：在 build 目录运行cmake-gui或ccmake查看并修正缓存变量，也可显式传入-DPython3_EXECUTABLE=...、-DCMAKE_PREFIX_PATH=...等提示路径；
• 头文件缺失报错：确认对应库的完整版本（含头文件）已通过 vcpkg 安装，且 triplet 与目标架构一致；
• 构建目录与编译器定义冲突：CMake 初始化 build 目录后再传入编译器相关变量会产生unable to execute ... clang++之类的错误，此时应清空 build 目录重新配置；
• DLL 找不到导致运行失败：先检查build\libopenage\<config>\是否已有完整 DLL，若没有，对照第 6.5 节从<vcpkg directory>\installed\<triplet>\bin手工补齐，并确认QML2_IMPORT_PATH、FONTCONFIG_PATH均已正确设置。

9. 小结

至此，一条完整的 Windows/MSVC 构建链路已经清晰：手动安装 Visual Studio Build Tools、Python 3、CMake → 用 pip 安装 Python 依赖 → 用 vcpkg 安装原生库（注意 triplet 与位数）→ 通过 vcpkg 工具链文件配置并编译 → 配置字体、fontconfig、QML 路径后以 devmode 运行 → 用 CPack/NSIS 产出安装包或便携包。每一步背后，doc/building.md 的依赖清单、buildsystem/scripts/EmbedWinDependencies.cmake 的 DLL 处理逻辑与 packaging/CPackOptions.cmake 的打包参数共同构成了可验证的依据。如果你只想体验 openage 而非从源码构建，建议优先使用官方发布的预编译安装包；本文面向的是希望参与开发、调试或自行定制构建的开发者。

• 游戏开发
• 图形学