企业官网建设流程全解析

• 数据工程
• 大数据
• 序列化
• 数据分析

本文是基于 Apache Arrow 官方开发者文档整理的 Windows 平台 C++ 构建实战指南。围绕当前仓库 docs/source/developers/cpp/windows.rst 展开，系统讲解在 Windows 上从零搭建 Arrow C++ 开发环境的方法：如何初始化 Visual Studio 命令行环境、如何用 conda-forge 或 vcpkg 管理第三方依赖，以及如何用 MSVC Solution、Ninja、NMake、MSYS2 等不同生成器完成 out-of-source 构建。读完本文，你将掌握在 Windows 上编译、调试、静态链接 Arrow C++ 库并复现 CI 构建的全套方法，并理解相关 CMake 选项在源码层的真实作用。

系统环境准备：Visual Studio 与命令行开发环境

与 Linux 和 macOS 一样，Arrow 的开发团队致力于让项目在 Windows 上通过 CMake「开箱即用」地完成构建——前提是你有一个可用的 C++ 编译工具链。微软提供了免费的Visual Studio Community版本，包含 MSVC 编译器和构建工具。

在命令行（cmd.exe / PowerShell）中做开发时，每次新开一个 shell 都必须重新初始化 Visual Studio 的开发环境，这会让cl.exe、nmake、ninja等工具进入 PATH，并配置好环境变量。

Visual Studio 2017 使用如下批处理脚本初始化（x64 架构）：

"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools\VsDevCmd.bat" -arch=amd64

Visual Studio 2019 对应的脚本为：

"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\VsDevCmd.bat" -arch=amd64

注意：新版 Visual Studio（2019 及以后）还提供位于VC\Auxiliary\Build\vcvarsall.bat的等价脚本，例如"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64。当前仓库的 Windows CI 脚本 ci/appveyor-cpp-setup.bat 正是通过call vcvarsall.bat amd64来完成这一步的。

此外，可以配置 cmder 之类的控制台模拟器，让它在每次启动新的开发控制台时自动执行上述初始化脚本，省去手动输入。

依赖管理方案一：使用 conda-forge 获取构建依赖

Miniconda是包含 conda 包管理器的精简版 Python 发行版。Apache Arrow 社区的成员长期参与维护conda-forge——一个由社区维护的跨平台 conda 软件包仓库。Arrow 在 Windows 上的 CI 也大量依赖 conda 提供预编译依赖。

使用 conda-forge 作为 C++ 构建依赖来源的步骤如下：

1. 从 Miniconda 官网下载并安装 64 位发行版；
2. 打开命令提示符（cmd.exe），先执行上文所述的环境初始化脚本（vcvarsall.bat或VsDevCmd.bat）；
3. 将 conda-forge 设为默认 channel：

conda config --add channels conda-forge

4. 在 Arrow 代码库根目录下，基于仓库提供的 ci/conda_env_cpp.txt 创建独立构建环境：

conda create -y -n arrow-dev --file=ci\conda_env_cpp.txt

5. 激活该环境：

activate arrow-dev

环境激活后，Arrow 的构建系统会自动检测到%CONDA_PREFIX%环境变量，并以此为依赖解析根目录。这等价于显式传入两个 CMake 参数：

-DARROW_DEPENDENCY_SOURCE=SYSTEM ^ -DARROW_PACKAGE_PREFIX=%CONDA_PREFIX%\Library

从源码层面看，这一自动探测逻辑位于 cpp/cmake_modules/DefineOptions.cmake：当CONDA_PREFIX环境变量非空时，ARROW_DEPENDENCY_SOURCE的默认值会被设为CONDA；而 cpp/cmake_modules/ThirdpartyToolchain.cmake 会在该模式下将ARROW_PACKAGE_PREFIX指向%CONDA_PREFIX%\Library（Windows 下 conda 的Library目录存放头文件与导入库），并据此批量设置各依赖的*_ROOT变量。

激活 conda 环境后，可以直接在同一个命令行里通过devenv启动 Visual Studio IDE，IDE 会继承当前环境的所有变量。

几点重要提醒：

• conda 安装的依赖包是Release 模式编译的，无法与 Debug 构建链接。如果打算使用-DCMAKE_BUILD_TYPE=debug，则必须从源码自行编译这些依赖。-DCMAKE_BUILD_TYPE=relwithdebinfo是另一种可用选项，它产出的构建既能与 Release 库链接，又保留可调试信息。
• 如果使用 conda 包遇到问题，最常见的原因是混用了defaultschannel 与conda-forgechannel 的包。可以用conda list查看当前环境中已安装的包及其来源。

依赖管理方案二：使用 vcpkg 获取构建依赖

vcpkg是微软开源的 C/C++ 包管理器，托管社区贡献的 C/C++ 库及其依赖的 ports。Arrow 在仓库根目录提供了 manifest 文件 cpp/vcpkg.json，声明了构建 C++ 库所需的全部 vcpkg 包，包括 abseil、aws-sdk-cpp、boost 系列、brotli、bzip2、c-ares、curl、flatbuffers、gflags、glog、google-cloud-cpp、grpc、gtest、lz4、openssl、orc、protobuf、rapidjson、re2、snappy、sqlite3、thrift、utf8proc、xsimd、zlib、zstd 等，并通过builtin-baseline与overrides（如固定 gtest 1.10.0）锁定版本行为。

使用 vcpkg 的步骤如下：

1. 先安装并集成 vcpkg 本身；
2. 在cmd.exe中切换工作目录到 Arrow 根目录，执行：

vcpkg install ^ --triplet x64-windows ^ --x-manifest-root cpp ^ --feature-flags=versions ^ --clean-after-build

其中--x-manifest-root cpp指向 manifest 文件所在目录（即仓库的cpp子目录），--clean-after-build在安装完成后清理构建中间文件。

在 Windows 上，vcpkg 默认构建动态链接库（DLL）；如需静态库，使用 tripletx64-windows-static。vcpkg 会下载源码包并在本地编译，因此用 vcpkg 安装依赖比 conda 更耗时。

然后，在 cmake 命令中通过-DARROW_DEPENDENCY_SOURCE=VCPKG让构建系统使用 vcpkg 安装的依赖。除该选项外，还可以用以下变量覆盖 vcpkg 的默认 CMake 配置：

这些选项的底层逻辑集中在 cpp/cmake_modules/Usevcpkg.cmake：该文件按「显式-DCMAKE_TOOLCHAIN_FILE→VCPKG_ROOT变量 →VCPKG_ROOT环境变量 →vcpkg.path.txt」的顺序定位 vcpkg 根目录；若未指定VCPKG_TARGET_TRIPLET，会从 vcpkg installed 目录下的子目录名自动推断；当cpp/vcpkg.json存在且未显式关闭时，VCPKG_MANIFEST_MODE会被自动置为ON；VCPKG_LIBRARY_LINKAGE（动态/静态）则由ARROW_DEPENDENCY_USE_SHARED决定。最终ARROW_DEPENDENCY_SOURCE会被强制设为SYSTEM（见 cpp/cmake_modules/Usevcpkg.cmake，注释明确说明 VCPKG 在内部实现为 SYSTEM），并预先为 Boost、OpenSSL、Thrift、ZSTD、Brotli、LZ4 等设置好指向 vcpkg 前缀的*_ROOT变量。

使用 Visual Studio（MSVC）Solution 文件构建

在cmd.exe中切换工作目录到 Arrow 根目录，进行 out-of-source 构建：先进入cpp子目录、创建build目录，然后生成 MSVC 解决方案并编译：

cd cpp mkdir build cd build cmake .. -G "Visual Studio 15 2017" -A x64 ^ -DARROW_BUILD_TESTS=ON cmake --build . --config Release

• -G "Visual Studio 15 2017"指定生成器（对应 VS 2017），-A x64指定目标平台为 64 位；
• -DARROW_BUILD_TESTS=ON开启单元测试构建；
• cmake --build . --config Release用 Release 配置编译解决方案。

对于更新版本的 Visual Studio，使用生成器名称Visual Studio 16 2019（以及更新的Visual Studio 17 2022），或运行cmake --help查看本机可用的生成器列表。

使用 Ninja 与 sccache 构建

Ninja构建系统提供了更好的构建并行度；可选的sccache编译器缓存会记录过去的编译结果以避免重复编译（机制与 Unix 下的ccache类似，且同样适用于 MSVC）。

较新版本的 Visual Studio 已内置 Ninja。检查方法：先运行环境初始化脚本（vcvarsall.bat或VsDevCmd.bat），再执行ninja --version。

如果所用的 Visual Studio 版本没有内置 Ninja：

• 使用 conda 时，激活arrow-dev环境后安装：

activate arrow-dev conda install -c conda-forge ninja

• 不使用 conda 时，从 Ninja 的预编译包渠道单独安装。

安装完成后，生成 Ninja 构建文件并编译（注意-DGTest_SOURCE=BUNDLED：由于 Ninja 不生成 VS 解决方案，GoogleTest 需要以内置源码形式参与构建）：

cd cpp mkdir build cd build cmake -G "Ninja" ^ -DARROW_BUILD_TESTS=ON ^ -DGTest_SOURCE=BUNDLED .. cmake --build . --config Release

若要以本地存储模式启用sccache，需在调用cmake之前设置SCCACHE_DIR环境变量：

... set SCCACHE_DIR=%LOCALAPPDATA%\Mozilla\sccache cmake -G "Ninja" ^ ...

使用 NMake 构建

NMake 是随 Visual Studio 分发的经典 make 工具。在cmd.exe中切换到 Arrow 根目录并执行：

cd cpp mkdir build cd build cmake -G "NMake Makefiles" .. nmake

注意 NMake 单线程执行，构建速度通常慢于 Ninja；该方式适合在没有 Ninja 的旧环境中应急使用。

在 MSYS2 上构建

MSYS2 提供了类 Unix 的终端环境。可以在MSYS2 终端、cmd.exe或PowerShell中进行构建。

在 MSYS2 终端中：

cd cpp mkdir build cd build cmake -G "MSYS Makefiles" .. make

在cmd.exe或 PowerShell 终端中，可以直接使用下面的批处理脚本（仓库目录下执行），它配置好 MINGW64 环境后使用 MSYS Makefiles 生成器构建：

setlocal REM For 64bit set MINGW_PACKAGE_PREFIX=mingw-w64-x86_64 set MINGW_PREFIX=c:\msys64\mingw64 set MSYSTEM=MINGW64 set PATH=%MINGW_PREFIX%\bin;c:\msys64\usr\bin;%PATH% rmdir /S /Q cpp\build mkdir cpp\build pushd cpp\build cmake -G "MSYS Makefiles" .. || exit /B make || exit /B popd

MSYS2 构建主要面向 MinGW-w64 工具链场景（例如在 Windows 上模拟 Unix 构建环境，或需要 GCC 而非 MSVC 的场景）。

在 Windows/ARM64 上使用 Ninja 与 Clang 构建

对于 Windows on ARM64（WoA64）平台，可以使用Ninja + clang组合构建 Arrow 库：

cd cpp mkdir build cd build set CC=clang-cl set CXX=clang-cl cmake -G "Ninja" .. cmake --build . --config Release

• 通过设置CC=clang-cl、CXX=clang-cl将编译器切换为 LLVM 的 MSVC 兼容前端；
• Windows/ARM64 的 LLVM 工具链可从 LLVM 官方 release 页面下载；
• 由于 xsimd、boost 等依赖在 ARM64 上存在兼容性问题，Visual Studio（MSVC）目前还不能用于编译 win/arm64 构建；
• 官方明确提示：该构建仅为 WoA64 的实验性支持，由于 CI 基础设施限制，并非所有特性都经过充分测试。

Debug 构建

要构建 Arrow 的 Debug 版本，需要预先安装Debug 版本的 Boost。推荐为 Debug 构建配置以下 CMake 变量：

• -DARROW_BOOST_USE_SHARED=OFF：启用与 boost debug 库的静态链接，简化第三方库的运行时加载；
• -DBOOST_ROOT：设置 boost 库根目录（可选）；
• -DBOOST_LIBRARYDIR：设置包含 boost 库文件的目录（可选）。

ARROW_BOOST_USE_SHARED的默认值由ARROW_DEPENDENCY_USE_SHARED决定（默认ON），定义于 cpp/cmake_modules/DefineOptions.cmake。在 Debug 模式下需要显式关闭共享链接，以避免链接到 Release 版 Boost 库。

Debug 模式构建命令行示例：

cd cpp mkdir build cd build cmake .. -G "Visual Studio 15 2017" -A x64 ^ -DARROW_BOOST_USE_SHARED=OFF ^ -DCMAKE_BUILD_TYPE=Debug ^ -DBOOST_ROOT=C:/local/boost_1_63_0 ^ -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0 cmake --build . --config Debug

Windows 依赖解析问题：静态库后缀处理

Windows 上无论静态还是动态链接，依赖库都使用.lib文件，因此静态库有时会被命名为形如%PACKAGE%_static.lib的独立名称以示区分。当静态链接某些依赖时，Arrow 提供了专门的 CMake 选项来指定这些后缀：

• -DBROTLI_MSVC_STATIC_LIB_SUFFIX=%BROTLI_SUFFIX%
• -DSNAPPY_MSVC_STATIC_LIB_SUFFIX=%SNAPPY_SUFFIX%
• -LZ4_MSVC_STATIC_LIB_SUFFIX=%LZ4_SUFFIX%
• -ZSTD_MSVC_STATIC_LIB_SUFFIX=%ZSTD_SUFFIX%

这些选项在 cpp/cmake_modules/DefineOptions.cmake 中定义。例如 Snappy 在 MSVC 下默认使用_static后缀（见 cpp/cmake_modules/DefineOptions.cmake），LZ4、ZSTD 的查找逻辑中同样在MSVC条件下默认追加_static（见 cpp/cmake_modules/Findlz4Alt.cmake 与 cpp/cmake_modules/FindzstdAlt.cmake）。当某个依赖的静态库命名不符合这些默认规则时，就需要用上述变量显式指定后缀。

获取最新的构建说明，可以直接参考仓库中 Appveyor 自动化构建使用的脚本 ci/appveyor-cpp-build.bat，其中展示了完整的 Windows 构建参数集。

在 Windows 上静态链接 Arrow

Windows 的静态库构建（由 CMake 选项ARROW_BUILD_STATIC启用，默认ON，见 cpp/cmake_modules/DefineOptions.cmake）产出的 Arrow 头文件使用预处理宏ARROW_STATIC来抑制符号的dllimport/dllexport标记。在 Windows 上静态链接 Arrow 的项目必须额外定义该宏；Unix 构建不使用此宏。

另外，如果启用了-DARROW_FLIGHT=ON，还需要定义ARROW_FLIGHT_STATIC；同理，-DARROW_FLIGHT_SQL=ON时需要定义ARROW_FLIGHT_SQL_STATIC。

一个完整的 CMake 静态链接示例：

project(MyExample) find_package(Arrow REQUIRED) add_executable(my_example my_example.cc) target_link_libraries(my_example PRIVATE arrow_static arrow_flight_static arrow_flight_sql_static) target_compile_definitions(my_example PUBLIC ARROW_STATIC ARROW_FLIGHT_STATIC ARROW_FLIGHT_SQL_STATIC)

下载时区数据库

Windows 上运行部分 compute 单元测试前，需要先下载IANA 时区数据库和Windows 时区映射表。下载方法可参考仓库脚本 ci/scripts/download_tz_database.sh：该脚本从 IANA 下载tzdata压缩包并解压，同时从 Unicode CLDR 项目下载windowsZones.xml（Windows 时区映射），两者一同放入~/Downloads/tzdata目录。当前仓库的 Windows CI 脚本 ci/appveyor-cpp-setup.bat 也执行了完全相同的下载流程。

若希望在运行单元测试时为时区数据库指定非默认路径，设置ARROW_TIMEZONE_DATABASE环境变量即可。

复现 Appveyor 构建

对于更熟悉 Linux 开发、但需要在本机复现失败的 Appveyor 构建（例如Static_Crt_Build任务）的开发者，以下是官方提供的复现笔记（make unittest可能仍然会失败，但绝大多数单元测试可以通过各自的独立 make target 构建出来）：

1. 准备虚拟机：微软为「带 Visual Studio 的 Windows」提供了试用虚拟机，下载并安装一个版本；
2. 安装基础工具：在虚拟机中安装 Git、CMake、Miniconda 或 Anaconda（以下步骤假设 Anaconda），并安装「Build Tools for Visual Studio」。安装向导中务必勾选C++ 工具链，安装完成后重启；
3. 安装预编译的 Boost Debug 二进制：下载 Boost 预编译二进制并安装。在 Anaconda/Miniconda 命令提示符（不要用 PowerShell）中执行，并先运行vcvarsall.bat x64。vcvarsall.bat的位置可能因版本而异，例如 VS 2019 Build Tools 下通常是C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat。随后编译静态 Boost 库：

cd $EXTRACT_BOOST_DIRECTORY .\bootstrap.bat @rem This is for static libraries needed for static_crt_build in appveyor .\b2 link=static --with-filesystem --with-regex --with-system install @rem this should put libraries and headers in c:\Boost

4. 激活 Anaconda/Miniconda：

@rem this might differ for miniconda C:\Users\User\Anaconda3\Scripts\activate

5. 克隆代码并切换到 Arrow 源码目录（可能需要先安装 git）；
6. 设置环境变量（按要复现的 Appveyor 任务调整构建类型）：

@rem Change the build type based on which appveyor job you want. SET JOB=Static_Crt_Build SET GENERATOR=Ninja SET APPVEYOR_BUILD_WORKER_IMAGE=Visual Studio 2017 SET USE_CLCACHE=false SET ARROW_BUILD_GANDIVA=OFF SET ARROW_LLVM_VERSION=8.0.* SET PYTHON=3.9 SET ARCH=64 SET PATH=C:\Users\User\Anaconda3;C:\Users\User\Anaconda3\Scripts;C:\Users\User\Anaconda3\Library\bin;%PATH% SET BOOST_LIBRARYDIR=C:\Boost\lib SET BOOST_ROOT=C:\Boost

7. 运行 Appveyor 脚本：

conda install -c conda-forge --file .\ci\conda_env_cpp.txt .\ci\appveyor-cpp-setup.bat @rem this might fail but at this point most unit tests should be buildable by there individual targets @rem see next line for example. .\ci\appveyor-cpp-build.bat @rem you can also just invoke cmake directly with the desired options cmake --build . --config Release --target arrow-compute-hash-test

其中ci\conda_env_cpp.txt是仓库内维护的 conda 依赖清单（见 ci/conda_env_cpp.txt），appveyor-cpp-setup.bat负责下载时区数据库、配置 Minio（S3 测试用）等准备工作，appveyor-cpp-build.bat则执行完整 CMake 配置与构建。如果脚本在某个环节失败，也可以直接用cmake加所需选项单独构建某个测试目标，例如上例中的arrow-compute-hash-test。

小结

在 Windows 上构建 Apache Arrow C++ 是一个「编译器环境初始化 + 依赖管理 + 生成器选择」的组合流程：先用VsDevCmd.bat/vcvarsall.bat初始化 MSVC 环境，再根据团队习惯从 conda-forge（预编译、速度快）与 vcpkg（manifest 化、版本可控）中二选一管理依赖，最后按需选择 MSVC Solution、Ninja（配合 sccache 加速）、NMake、MSYS2 或 ARM64 专属的 clang-cl 方案完成构建。调试场景记得为 Boost 准备 Debug 版并关闭共享链接，静态链接场景则要定义ARROW_STATIC系列宏。本文所有命令均可直接在当前仓库中验证对应源码与 CI 脚本，遇到问题时以 ci/appveyor-cpp-build.bat 中的完整参数集为权威参考。

• 数据工程
• 大数据
• 序列化
• 数据分析