在 WSL2 中编译 ONLYOFFICE Core 模块的踩坑记录（续）
编译日期：2026-09-24 ~ 2026-09-28 编译目标：ONLYOFFICE Core → Builder 模块（linux_64 / linux_arm64 / win_64） 本文续接：坑十二至坑十四，附录 C/D
坑十二：WSL 中无法交叉编译 win_64
背景
在 core 模块编译通过后，继续编译 builder 模块：
python3 ./automate.py builder --update=0 --clean=0 --platform=win_64
现象
编译过程未报错，最终 deploy 阶段全部文件缺失：
copy warning [file not exist]: .../core/build/lib/win_64/libkernel.so
copy warning [file not exist]: .../core/build/lib/win_64/libgraphics.so
copy warning [file not exist]: .../core/build/bin/win_64/x2t
...
/bin/sh: 1: ./x2t: not found
注意文件扩展名是 .so（Linux）而非 .dll（Windows）。
原因
根本原因：WSL Linux 环境不支持交叉编译 win_64。
失败链条如下：
关键设计缺陷：copy_lib() 和 copy_exe() 使用 host_platform() 而非目标平台来决定文件扩展名：
# scripts/base.py:286 — copy_lib
lib_ext = ".so"
if ("windows" == host_platform()): # ← WSL 返回 "linux"，永远用 .so
lib_ext = ".dll"
# scripts/base.py:313 — copy_exe
exe_ext = ""
if ("windows" == host_platform()): # ← WSL 返回 "linux"，不加 .exe
exe_ext = ".exe"
解决
WSL 中无法交叉编译 win_64，必须改用以下方案之一：
方案 A（推荐）：在 Windows 上直接构建
# Windows PowerShell 中执行
cd E:\Code\ONLYOFFICE\build_tools\tools\win
python configure.py --module builder --platform win_64 --update 0 --qt-dir <Windows Qt 路径>
python make.py
前提：安装 Visual Studio 2015/2019 + Windows 版 Qt 5.9.9（msvc2015_64）
方案 B（最简单）：改为构建 linux_64
python3 ./automate.py builder --update=0 --clean=0 --platform=linux_64
结论
ONLYOFFICE 的 build_tools 不支持从 WSL Linux 交叉编译 win_64。qt_binary_fetch.py 仅提供 Linux Qt 下载，且 copy_lib/copy_exe 存在使用 host_platform() 而非目标平台的设计缺陷。
坑十三：pip 安装的 cmake 4.4.3 与 libheif 不兼容
背景
在 linux_64 编译通过后，尝试编译 linux_arm64：
python3 ./automate.py builder --update=0 --clean=0 --platform=linux_arm64
现象
heif 模块编译时 cmake 配置失败：
-- cmake version 4.4.3
CMake Error at CMakeLists.txt:10 (cmake_policy):
Policy CMP0025 may not be set to OLD behavior because this version of CMake
no longer supports it.
CMake Error at CMakeLists.txt:16 (cmake_policy):
Policy CMP0054 may not be set to OLD behavior because this version of CMake
no longer supports it.
CMake Error at CMakeLists.txt:20 (cmake_minimum_required):
Compatibility with CMake < 3.5 has been removed from CMake.
-- Configuring incomplete, errors occurred!
Error (cmake): 1
原因
build_tools 的 Python3 虚拟环境（tools/linux/python3/）中通过 pip 安装了 cmake==4.4.3：
/mnt/wsl/onlyoffice/build_tools/tools/linux/python3/lib/python3.10/site-packages/cmake-4.4.3.dist-info
automate.py 将 tools/linux/python3/bin/ 放在 PATH 最前面，导致所有 cmake 调用使用的都是 4.4.3 版本。
而 heif 模块的源码注释明确写着：
# scripts/core_common/modules/heif.py 第4行
# NOTE:
# - requires CMake >= 3.21, < 4.0.0
CMake 4.x 移除了对旧策略（CMP0025 OLD、CMP0054 OLD）和 cmake_minimum_required < 3.5 的支持，导致 libheif 1.18.2 的 CMakeLists.txt 配置失败。
补充说明：cmake.sh 脚本本来会安装 cmake 3.30.0 到 /usr/local/bin/cmake，但 pip 的 cmake 4.4.3 在 PATH 中优先级更高，将其覆盖了。
解决
降级 pip 安装的 cmake 到 3.30.x：
cd /mnt/wsl/onlyoffice/build_tools/tools/linux
./python3/bin/pip3 install cmake==3.30.4
验证：
./python3/bin/cmake --version
# 应输出：cmake version 3.30.4
降级后重新编译即可通过 heif 模块。
补充
这与坑十（系统 cmake 版本过低不支持 --preset）形成了「两面夹击」：
注意：坑十的解决方案是用 pip3 install cmake --upgrade 升级 cmake，但 pip 默认会安装最新版（4.4.3），从而触发了坑十三。正确的做法是指定版本：pip3 install cmake==3.30.4。
坑十四：linux_arm64 交叉编译器未安装
背景
尝试在 WSL x86_64 环境中编译 linux_arm64 目标平台。
现象
编译到需要交叉编译的阶段时，找不到 aarch64-linux-gnu-gcc 交叉编译器。
原因
WSL 环境中只安装了原生 x86_64 的 gcc/g++，未安装 ARM64 交叉编译器。build_tools 的 config.py 在检测到 linux_arm64 且非 ARM 主机时，会使用 aarch64-linux-gnu-gcc 作为编译器（见 system-aarch64.toolchain.cmake）。
解决
安装 ARM64 交叉编译器：
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
安装后即可编译：
python3 ./automate.py builder --update=0 --clean=0 --platform=linux_arm64
补充：WSL 中可编译的平台总结
坑十五：linux_arm64 deploy 阶段缺少 QEMU 用户态模拟器
背景
在 linux_arm64 编译通过后，deploy 阶段最终报错：
Done.
Cleaning deploy directory...
Building word...
Building cell...
Building slide...
Building visio...
Copying other files...
Build complete.
Directory not copied
/bin/sh: 1: qemu-aarch64: not found
注意：编译本身已经成功（日志中有 "Build complete."），失败发生在 deploy 阶段。
原因
deploy_builder.py 在 deploy 结束后会调用 create_x2t_js_cache()（scripts/base.py:2079）生成 JS 快照。该函数在检测到 linux_arm64 且非 ARM 主机时，会使用 QEMU 模拟运行 ARM64 的 x2t 二进制来生成 JS 快照：
# scripts/base.py:2085-2087
if ((platform == "linux_arm64") and not is_os_arm()):
cmd_in_dir_qemu(platform, dir, "./x2t", ["-create-js-snapshots"], True)
return
cmd_in_dir_qemu()（scripts/base.py:438）直接调用 qemu-aarch64 来模拟运行：
# scripts/base.py:441-457
def cmd_in_dir_qemu(platform, directory, prog, args=[], is_no_errors=False):
platform_config = {
"linux_arm64": {
"qemu": "qemu-aarch64",
"default_libs": "/usr/aarch64-linux-gnu"
},
...
}
libs_path = platform_config[platform]["default_libs"]
if config.option("sysroot") != "":
libs_path = config.option("sysroot_" + platform)
return cmd_in_dir(directory, platform_config[platform]["qemu"], ["-L", libs_path, prog] + args, is_no_errors)
WSL 环境中 未安装 QEMU 用户态模拟器：
which qemu-aarch64 → NOT_FOUND
而 ARM64 的 x2t 二进制无法在 x86_64 上直接运行：
$ file core/build/bin/linux_arm64/x2t
ELF 64-bit LSB executable, ARM aarch64, version 1 (GNU/Linux), dynamically linked,
interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.7.0
解决
安装 QEMU 用户态模拟器：
sudo apt install qemu-user qemu-user-static binfmt-support
安装后 qemu-aarch64 命令即可用，重新运行：
python3 ./automate.py builder --update=0 --clean=0 --platform=linux_arm64
补充
该调用使用了 is_no_errors=True 参数，所以即使 QEMU 运行失败也不会中断编译——它只影响 JS 快照的生成。如果产物不需要 JS 快照（仅用于部署环境运行 x2t），编译产物本身已经是完整的，可以忽略此错误。
但如果不安装 QEMU，/bin/sh: 1: qemu-aarch64: not found 错误会一直出现，建议安装以获得完整产物。
附录 C：WSL 平台支持矩阵
Qt 版本对应关系
cmake 版本要求矩阵
build_tools 中的 cmake 来源
正确做法：pip 安装时锁定版本 pip3 install cmake==3.30.4
附录 D：编译命令速查
Core 模块
# linux_64（推荐）
python3 ./automate.py core --update=0
# linux_arm64（需先安装交叉编译器）
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
python3 ./automate.py core --update=0 --platform=linux_arm64
Builder 模块
# linux_64（推荐）
python3 ./automate.py builder --update=0 --clean=0 --platform=linux_64
# linux_arm64
python3 ./automate.py builder --update=0 --clean=0 --platform=linux_arm64
# win_64（需在 Windows 上执行，WSL 不支持）
# Windows PowerShell:
cd E:\Code\ONLYOFFICE\build_tools\tools\win
python configure.py --module builder --platform win_64 --update 0
python make.py
关键环境变量
# cmake 版本锁定（防止坑十和坑十三同时出现）
export PATH="/mnt/wsl/onlyoffice/build_tools/tools/linux/python3/bin:$PATH"
pip3 install cmake==3.30.4
# JAVA_HOME（解决坑十一）
export JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"
export PATH="$JAVA_HOME/bin:$PATH"
# Git 版本警告抑制
export GCLIENT_SUPPRESS_GIT_VERSION_WARNING=1
环境信息
操作系统
编译工具链
构建工具版本
WSL 中的 Qt 目录
qt_build/Qt-5.9.9/
├── gcc_64/ # Linux x64
├── gcc_arm64/ # Linux ARM64
├── qt_binary_5.9.9_gcc_64.7z # 安装包（amd64）
└── qt_binary_5.9.9_gcc_arm64.7z # 安装包（arm64）