在 Windows 10 中编译 ONLYOFFICE 模块的踩坑记录

适用环境：Windows 10/11 x64，ONLYOFFICE 核心源码 v9.4.0.131（branch="tags/v9.4.0.131"），平台 win_64。记录时间：2026-10-01。本文档按构建顺序记录各阶段遇到的问题、根因与解决办法，供后续重装/重编参考。

1. 总体环境要求

ONLYOFFICE build_tools（该版本）官方仅支持 VS2015 / VS2019，脚本的探测逻辑都按这两个版本写死。不要使用 VS2022/2026 等新版本编译（目录布局与工具链探测均不兼容，属于无底洞）。

必装软件清单

软件	版本/说明	用途
Visual Studio 2019 Build Tools	v16.11，含 MSVC v142（14.29）工具集	主编译器
Windows 10 SDK	10.0.19041.0 + Debugging Tools for Windows（调试工具）	v8 构建需要 Debuggers 里的 dbghelp.dll
.NET Framework 4 目标包	".NET Framework 4 targeting pack"（单个组件里勾选）	icu 的 makedata.vcxproj 目标框架 v4.0
Python	3.8 – 3.12（系统级，非 venv；3.13 移除了 v8 脚本用到的 `pipes` 模块）	gn/exec_script、各构建脚本
Strawberry Perl	scoop: `scoop install perl`	icu 数据构建
Git for Windows	官方布局（路径中须有名为 `git` 的目录），见第 8 节	depot_tools bootstrap
7-Zip / curl 等	build_tools 自带（tools/win 下），无需自装	解压、下载

VS2019 Build Tools 安装方式

新版 Visual Studio Installer 的"可用"列表不显示 VS2019，必须用专用引导程序：

Invoke-WebRequest -Uri "https://aka.ms/vs/16/release/vs_buildtools.exe" -OutFile "$env:TEMP\vs_buildtools2019.exe"

静默安装（含所需组件）：

vs_buildtools2019.exe --quiet --wait --norestart ^
  --add Microsoft.VisualStudio.Workload.VCTools ^
  --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 ^
  --add Microsoft.VisualStudio.Component.Windows10SDK.19041 ^
  --includeRecommended

后补组件（同样用 --modify 方式添加）：

Microsoft.VisualStudio.Component.Windows10SDK.DebuggingTools（调试工具）
.NET Framework 4 targeting pack（中文组件名：".NET Framework 4 目标包"）

安装后验证：

dir "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat"
dir "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\dbghelp.dll"
dir "C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0"

三者都存在即环境就绪。

build_tools 配置文件（build_tools\config，无扩展名文本文件）

关键条目：

platform="win_64"
vs-version="2019"
vs-path="C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build"

⚠️ vs-path 必须显式写出：scripts/config.py 的 2019 自动探测只认 Enterprise/Professional/Community 三个目录，不认 BuildTools。

2. 构建入口与推荐方式（build.bat）

不要用一行长命令串联（set VAR=... && 会把 && 前的空格带入变量值；PowerShell 的 $env: 设置也不会传回 cmd）。推荐写一个 build_tools\build.bat：

@echo off
call "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
set PATH=%USERPROFILE%\Code\ONLYOFFICE\build_tools\.venv\Scripts;C:\dev-tools\git\cmd;%PATH%
set HTTPS_PROXY=http://<代理IP>:<端口>(按本机实际填写)
set HTTP_PROXY=http://<代理IP>:<端口>(按本机实际填写)
set DEPOT_TOOLS_WIN_TOOLCHAIN=0
set VSLANG=1033
set PYTHONIOENCODING=utf-8
cd /d %USERPROFILE%\Code\ONLYOFFICE\build_tools
python make.py

要点：

vcvarsall x64 必须先执行：boost 的 bootstrap.bat 只在 PATH/当前目录找 vcvarsall，不读脚本配置的 vs-path；
PATH 里必须有一个非 venv 的系统 Python（供 gn 的 exec_script 使用，原因见第 8 节末尾）；
C:\dev-tools\git\cmd 置顶（原因见第 8 节）；
set PATH=...;%PATH% 行尾不要留空格。

3. 阶段一：Boost 构建失败

现象

Building Boost.Build engine
'cl' 不是内部或外部命令...
Failed to build Boost.Build engine.

根因

bootstrap.bat 内部执行 Call_If_Exists "VCVARSALL.BAT" x86，只在 PATH/当前目录找，找不到则 cl 不在 PATH。

解决

在初始化过 VS 环境的 cmd 中运行 make.py（见第 2 节 build.bat）。同时 build_tools\config 中按第 1 节配置 vs-version / vs-path。

4. 阶段二：Boost b2 引擎找不到 vcvarsall

现象（换用 VS2026 编译时出现，现已放弃该路线）

error: Name clash for '...libboost_chrono-vc142-mt-gd-1_72.lib'
error: Tried to build the target twice, with property sets having
error: these incompatible properties:
error:     -  <address-model>32
error:     -  <address-model>64

根因

boost 1.72 自带的老 b2 引擎按旧版 VS 目录布局拼 vcvarsall 路径（拼到 ...\MSVC\<版本>\bin\Hostx64\vcvarsall.bat），VS2026 中该文件不存在 → msvc-setup 被跳过 → address-model 探测失败 → 32/64 属性冲突。详见 bin.v2/config.log 中的 don't know how to make ... vcvarsall.bat。

结论

不要尝试在新版 VS 上修补（无论改脚本还是 project-config.jam），直接换 VS2019 Build Tools（第 1 节）。

换环境后若残留旧状态，清理：

cd %USERPROFILE%\Code\ONLYOFFICE\core\Common\3dParty\boost\boost_1_72_0
Remove-Item -Recurse -Force bin.v2, stage -ErrorAction SilentlyContinue

5. 阶段三：cef 下载失败（curl 代理语法错误）

现象

curl: (5) Unsupported proxy syntax in 'http://<代理IP>:<端口>(按本机实际填写) '

根因

cmd 中 set HTTPS_PROXY=http://x:7897 && 下一条命令 会把 && 前的空格包含进变量值，curl 收到带尾随空格的代理地址。

解决

set 与 && 之间不留空格，或干脆用 build.bat 逐行 set（推荐）。

6. 阶段四：icu 编译失败（MSB3644）

现象

error MSB3644: 找不到 .NETFramework,Version=v4.0 的引用程序集。

根因

icu 的 source\data\makedata.vcxproj 目标框架是 .NET Framework 4.0，VS2019 Build Tools 默认不带 4.0 目标包。

解决

Visual Studio Installer → Build Tools 2019 → 修改 → 单个组件 → 勾选 ".NET Framework 4 目标包"（英文 ".NET Framework 4 targeting pack"）。验证：

dir "C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0"

7. 阶段五：icu 需要 Perl

现象

'perl' 不是内部或外部命令...
NMAKE : fatal error U1073: 不知道如何生成"clean" / "build_libs"

根因

icu 数据构建（makedata）依赖 Perl。

解决

scoop install perl

（装完需新开命令行使 PATH 生效。）

8. 阶段六：v8/depot_tools 全流程问题

v8 8.9 通过 depot_tools（gclient/fetch）拉取并 gn/ninja 编译，是问题最集中的环节。

8.1 python3_bin_reldir.txt not found（depot_tools 未引导）

python3_bin_reldir.txt not found. need to initialize depot_tools

根因：v8_89.py 设置 DEPOT_TOOLS_UPDATE=0（防止自动更新覆盖补丁），depot_tools 自举（下载自带 python3/cipd）永远不会自动执行，fetch v8 静默失败。

解决：手动引导一次（只需一次）：

cd /d %USERPROFILE%\Code\ONLYOFFICE\core\Common\3dParty\v8_89
set HTTPS_PROXY=http://<代理IP>:<端口>(按本机实际填写)
set HTTP_PROXY=http://<代理IP>:<端口>(按本机实际填写)
set DEPOT_TOOLS_WIN_TOOLCHAIN=0
depot_tools\update_depot_tools.bat
dir depot_tools\python3_bin_reldir.txt

⚠️ 不要删 v8.data——删除会触发 common_check_version 走 clean() 分支，把 depot_tools 和 v8 目录整体删除重新克隆，前功尽弃。

8.2 depot_tools 找不到 Git（scoop 布局不兼容）

现象 A

ERROR:root:Git was not found in PATH. Have you installed it?

现象 B

ERROR:root:Found a Git installation but could not locate git.exe within it.

根因（depot_tools/bootstrap/bootstrap.py 的 search_win_git_directory）：

遍历 PATH 找含 git.exe 的目录；
从该目录向上查找名字恰好叫 git 的目录（_traverse_to_git_root）作为 Git 安装根（官方布局 C:\Program Files\Git\cmd\git.exe）；
scoop 的布局 ...\scoop\apps\git\current\cmd\git.exe 祖先链中没有叫 git 的目录（shims 亦然），MSYS2 布局检测也不匹配 → 必然失败。

scoop 版 Git 无论怎么调 PATH 都过不了该检测，不是配置问题，是布局不兼容。

解决（零修改脚本）：建一个目录联接，把 scoop Git 挂到名为 git 的路径下：

mkdir C:\dev-tools
mklink /J C:\dev-tools\git "%USERPROFILE%\scoop\apps\git\current"

验证（检测逻辑要求的文件都要在）：

dir C:\dev-tools\git\cmd\git.exe
dir C:\dev-tools\git\usr\bin\ssh.exe

构建时把 C:\dev-tools\git\cmd 放到 PATH 最前（build.bat 已含）。

备选方案：winget install --id Git.Git -e 装官方版到 C:\Program Files\Git，同样符合检测。若用此方案，需确保官方 git 在 PATH 中排在 scoop shims 之前。

8.3 gn 找不到 python（venv 被 PruneVirtualEnv 剔除）

现象

WARNING Could not find python on path, using just "python.exe"
ERROR at //build/config/win/visual_studio_version.gn:27:7: Could not execute interpreter.

根因：depot_tools 的 gn.py 在启动 gn 前执行 PruneVirtualEnv()，会把 PATH 中含 activate_this.py 的目录全部剔除——项目 .venv\Scripts 正好含该文件，于是 venv 的 python 被从 PATH 删掉，gn 的 exec_script 无解释器可用。

解决：PATH 里提供一个非 venv 的系统级 Python（3.8–3.12）：

scoop install python

（或 python.org 官方安装器，勾选 Add to PATH；注意 3.13+ 移除了 pipes 模块，v8 的 vs_toolchain.py 会挂。）

make.py 本身用 venv python 跑没问题，关键是 PATH 中有普通 python.exe。

8.4 v8 gn gen 报缺 dbghelp.dll（Windows SDK 调试工具）

现象

Exception: dbghelp.dll not found in "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\dbghelp.dll"
You must install Windows 10 SDK version 10.0.19041.0 including the "Debugging Tools for Windows" feature.

解决：

方式一：VS Installer → Build Tools 2019 → 修改 → 单个组件 → 勾选 "调试工具"（Debugging Tools for Windows，中文界面搜"调试"）；
方式二（推荐，已验证可用）：单独下载 Windows SDK 10.0.19041 官方安装器，安装时勾选 "Windows SDK Debugging Tools"（中文界面叫"调试工具"）：
winsdksetup.exe 直链：
```
https://go.microsoft.com/fwlink/?linkid=2120843
```
说明：
- 该直链对应 SDK 版本 10.0.19041.0（v8 的 vs_toolchain.py 指定要求该版本，更高版本不行——它查的是 Debuggers 目录下固定 SDK 的 dbghelp.dll）；
- 安装时只需勾选 "调试工具"（其它组件 VS2019 已带，不必重复安装）；
- 若需离线包：winsdksetup.exe /layout <目录> 可先下载完整安装媒体；
- 其它 SDK 版本的直链规则同理（可在微软开发者网站 "Windows SDK archive" 页面查询各版本的 fwlink）。

注意：如果装了多个 SDK 版本，v8 只认 10.0.19041.0 的 Debuggers 目录，装 10.0.22621 等新版的调试工具无效。

验证：

dir "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\dbghelp.dll"

8.5 中文系统导致的 Python 编解码崩溃（v8 link 阶段）

现象 1：decode 崩溃

File ".../build/toolchain/win/tool_wrapper.py", line 144, in ExecLinkWrapper
    line = line.decode('utf8')
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd5 in position 2

根因：中文 Windows 上 link.exe 输出 GBK 消息（如“正在创建库”），该脚本按 utf-8 逐行解码。

注意两个坑：

VSLANG=1033（强制 MSVC 工具输出英文）理论上可根治，但链接器环境来自 gn gen 生成时的快照 out.gn/win_64/release/environment.x64，实测该快照未包含 VSLANG，事后设置无效；
build_tools 的 v8_89.py（约 168-174 行）每次构建都检测 tool_wrapper.py 是否含字符串 line = line.decode('utf8')，不含就自动插回一行裸的 decode——手工改成容错版（不含该标记字符串）会被脚本再插回原行，插回的行在前面先执行、先崩溃。

最终解法（一行同时绕过检测 + 运行时容错）：把 tool_wrapper.py 中 ExecLinkWrapper 的该行写成：

      line = line.decode('utf8') if 0 else line.decode('utf8', errors='replace')

含标记字符串 → v8_89.py 不再插入；
运行时 if 0 恒假，实际执行容错解码。

⚠️ v8 重新拉取（v8.data 版本变更触发 clean）后此改动会还原，需重改。

现象 2：print 崩溃（decode 修复后出现）

File "...tool_wrapper.py", line 148, in ExecLinkWrapper
    print(line)
UnicodeEncodeError: 'gbk' codec can't encode character '\ufffd'

根因：解码容错产生替换符 \ufffd，print 到 GBK 控制台时编码失败。

解法：build.bat 加 set PYTHONIOENCODING=utf-8（日志可能乱码，不影响编译产物）。

8.6 缺 cmake

'cmake' 不是内部或外部命令

解法：scoop install cmake，重开命令行窗口（新 PATH 需新进程），再跑 build.bat。

⚠️ CMake 必须是 3.x，不能用 4.x：scoop 默认装的 cmake 4.4+ 已移除对旧策略（CMP0025/CMP0054 等的 OLD 行为）的支持，ONLYOFFICE 老 CMakeLists.txt 会报 Policy CMP0025 may not be set to OLD behavior 类错误。降级：

scoop install cmake@3.31.6
scoop reset cmake@3.31.6   # 若同时存在 4.x，用 reset 切换 shims 指向
cmake --version            # 必须显示 3.x

（或手动解压 cmake-3.31.x 到 C:\dev-tools 并把 bin 目录加入 build.bat PATH 前段。）

8.7 docbuilder.com/.net 报 devenv 不是内部或外部命令

call devenv docbuilder.com_2019.sln /Rebuild "Release|x64"
'devenv' 不是内部或外部命令

根因：这两个 COM/.NET 包装项目用 devenv（VS IDE 命令行）构建，devenv.exe 只存在于完整版 Visual Studio（Community/Professional/Enterprise），Build Tools 不带。且 base.py 的 make_sln 探测只认 Community/Enterprise/Professional 目录，不认 BuildTools。

影响：该调用以 is_no_errors=True 忽略失败继续，其它产物不受影响；仅 docbuilder 的 COM/.NET 包装组件缺失（X2tConverter 本体走 qmake/Qt，无影响）。

解法（可选）：需要完整组件时安装 VS2019 Community（https://aka.ms/vs/16/release/vs_community.exe，勾 C++ 工作负载），装完 base.py 自动探测到 ...\2019\Community\Common7\IDE；不需要可忽略。

8.8 js 阶段缺 grunt

'grunt' 不是内部或外部命令
Error (grunt):

背景：v8 编译完成后进入 js 构建阶段（sdkjs/web-apps 等，scripts/build_js.py 调用 grunt）。npm install 已自动跑过，只缺全局 grunt 命令。

解法：

npm install -g grunt-cli
grunt --version   # 验证；找不到则用 npm config get prefix 查全局 bin 目录并加入 PATH

之后重开窗口跑 build.bat。

8.9 sdkjs build.py 报 argparse 无 BooleanOptionalAction（Python 版本过低）

File "sdkjs/build/build.py", line 255, in main
    parser.add_argument('--minimize', action=argparse.BooleanOptionalAction, ...)
AttributeError: module 'argparse' has no attribute 'BooleanOptionalAction'

根因：BooleanOptionalAction 是 Python 3.9+ 的 API，环境里 python 为 3.8（venv 与 uv python 均为 3.8）。

解法 A（推荐）：装系统级 Python 3.9–3.12（不能 3.13+，v8 的 vs_toolchain.py 依赖已移除的 pipes 模块；v8 已编完，限制宽松）：

scoop install python@3.12.10

并在 build.bat 的 PATH 中把 3.12 目录排在 .venv\Scripts（3.8）之前：

set PATH=%USERPROFILE%\scoop\apps\python\3.12.10;%USERPROFILE%\scoop\apps\python\3.12.10\Scripts;%USERPROFILE%\Code\ONLYOFFICE\build_tools\.venv\Scripts;...

解法 B（不便换 Python 时）：给 sdkjs/build/build.py 加兼容定义（插在 import argparse 之后）：

if not hasattr(argparse, 'BooleanOptionalAction'):
    class BooleanOptionalAction(argparse.Action):
        def __init__(self, option_strings, dest, default=None, required=False, help=None):
            self.option_strings = option_strings
            self.dest = dest
            self.default = default
            self.required = required
            self.help = help
            super().__init__(option_strings, dest, nargs=0, default=default,
                             required=required, help=help)
        def __call__(self, parser, namespace, values, option_string=None):
            setattr(namespace, self.dest, not option_string.startswith('--no-'))

8.10 nvm 布局导致 grunt 在 cmd 中找不到

背景：node 由 nvm（scoop persist 布局）管理，npm install -g grunt-cli 装到版本目录 persist\nvm\nodejs\v22.23.3\（grunt.cmd 在此），但 cmd PATH 生效的是 persist\nvm\.nodejs（激活目录），二者不一致 → where grunt 找不到。

解法：build.bat 的 PATH 前面加版本目录：

set PATH=%USERPROFILE%\scoop\persist\nvm\nodejs\v22.23.3;...

（以后 nvm 切换 node 版本需同步改此行；更省心的替代是 scoop install nodejs-lts 用固定目录。）

附：构建中各 js 子项目的 npm audit 提示与 ENOLOCK 报错均可忽略，不影响构建。

8.11 deploy 阶段出现大量 copy warning 与 x2t 运行失败

Building word/cell/slide/visio... Build complete.
copy warning [file not exist]: ...core/build/lib/win_64/kernel.dll（以及 x2t.exe、doctrenderer.dll 等一系列）
'.\x2t' 不是内部或外部命令

性质：不是错误。js 阶段（word/cell/slide/visio 构建脚本）完成后会顺带执行一次 deploy 试拷贝；此时 core 的 C++ 产物（kernel.dll、UnicodeConverter.dll、x2t.exe、docbuilder 等）尚未编译，拷贝全部跳过，最后的 x2t 运行失败也是因为文件不存在。

处理：无需处理，继续 make.py 进入 core 编译阶段（Qt/qmake + MSVC，量最大、耗时最长；需先编译 Qt 5.15.x，4 核机器需数小时）。core 产物就绪后 deploy 阶段会自动补拷贝。

8.12 core C++ 编译：缺 3dParty 源码（C1083 找不到头文件）

sfwoff2.c(27): fatal error C1083: 无法打开包括文件: “brotli/decode.h”
TextShaper.cpp(655): fatal error C1083: 无法打开包括文件: “hb.h”

根因：core/Common/3dParty/<模块>/ 下的源码目录是“目录存在即跳过”的 fetch 逻辑。早期多轮中断的 make.py 里，brotli/harfbuzz 等模块的 fetch 从未执行，core 阶段才暴露。另外 harfbuzz 的 harfbuzz.pri（INCLUDEPATH）由 make.py 在 fetch 块内生成——若源码目录已存在但 pri 未生成（fetch 被跳过），同样报 C1083（即便 hb.h 物理存在）。

修复：删除源码目录 + module.version，让 make.py 完整重走“克隆→补丁→生成 pri”：

rmdir /s /q %USERPROFILE%\Code\ONLYOFFICE\core\Common\3dParty\harfbuzz\harfbuzz
del %USERPROFILE%\Code\ONLYOFFICE\core\Common\3dParty\harfbuzz\module.version

结论备忘：glew 不需要（当前分支无引用且仅 mobile 模块用）；html/md/hyphen/googletest/hunspell/heif/brotli 均已就位或按同样方法修复。

8.13 openssl Windows 构建产物为空（openssl/sha.h 找不到）

根因：openssl/build/win_64 是空目录（构建早期中断留下），脚本“目录存在即跳过”导致重编被跳过。且 openssl 构建需要 Perl——Git Bash 自带的 cygwin perl 与 openssl 1.1.1 的 Configure 存在兼容问题，需用 Strawberry Perl。

修复：

rmdir /s /q %USERPROFILE%\Code\ONLYOFFICE\core\Common\3dParty\openssl\build\win_64
set PATH=%USERPROFILE%\scoop\apps\perl\current\bin;%PATH%

然后重跑 build.bat（脚本会重新 Configure + nmake build_libs install）。

8.14 DefaultNotesTheme.cpp 报 C2059/C2017（MSVC 用 GBK 解析 UTF-8 无 BOM 源文件）

DefaultNotesTheme.cpp(45): error C2440: 无法从“const char [56]”转换
DefaultNotesTheme.cpp(47): error C2059: 语法错误:“>”
DefaultNotesTheme.cpp(121): error C2017: 非法的转义序列

根因（两重，均已验证）：

主因：源码字符集。该文件为 UTF-8 无 BOM，含大量非 ASCII 字体名（ＭＳＰゴシック、맑은 고딕、宋体 等）。MSVC 默认按系统 ANSI 代码页（中文系统 GBK）解析，多字节错乱破坏了字符串字面量的转义结构（\" 的 \ 被吞进多字节序列），产生 C2017/C2059/C2679 连锁报错。Linux 下 gcc 默认 UTF-8，官方从未暴露。 验证方法：cl /nologo /c /TP /EHsc /D_UNICODE /source-charset:utf-8 DefaultNotesTheme.cpp → 编译通过（OBJ 生成）。修复（已实施）：build_tools/scripts/qmake.py 的 windows 分支给所有项目追加独立 qmake 参数 QMAKE_CXXFLAGS+=/utf-8 QMAKE_CFLAGS+=/utf-8（不放进 qt_config 的 CONFIG 串——Qt 5.6 分支整串合并进 CONFIG+= 会让赋值失效）。
伴生因素：git autocrlf。core.autocrlf=true checkout 时把源文件 LF 转 CRLF，XML 字面量里的 \+CRLF 续行本身也是 MSVC 不接受的写法（官方仓库 LF 无此问题）。已通过 .gitattributes（*.cpp/*.h/*.c/*.hpp/*.pri/*.pro text eol=lf，已暂存）+ 手动转换已 CRLF 化的文件解决。转换后 git status 显示 modified 属预期，不要 checkout 恢复。

单文件验证命令：

cd /d %USERPROFILE%\Code\ONLYOFFICE\core\OOXML\Binary\Presentation
call "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
cl /nologo /c /TP /EHsc /D_UNICODE /source-charset:utf-8 DefaultNotesTheme.cpp

8.16 build.bat 生成（汇总）

构建入口脚本：%USERPROFILE%\Code\ONLYOFFICE\build.bat（纯 ASCII + CRLF，避免批处理编码问题；中文注释曾导致批处理报乱码错误——.bat 文件只能用 ASCII/ANSI 注释）。

要点：

vcvarsall x64 初始化 VS2019 环境；
PATH 顺序：Strawberry Perl（scoop\apps\perl\current\perl\bin，需排最前避免 Git 的 cygwin perl 干扰 openssl/icu 构建）→ Python 3.12（uv 管理，sdkjs 需要 ≥3.9）→ nvm node 版本目录（grunt-cli 所在）→ venv 3.8 → git junction（C:\dev-tools\git\cmd）→ scoop shims；
HTTPS_PROXY/HTTP_PROXY 代理（按本机实际填写）；
DEPOT_TOOLS_WIN_TOOLCHAIN=0、VSLANG=1033、PYTHONIOENCODING=utf-8；
CL=/utf-8 全局兜底（配合 qmake.py 按项目注入的 /utf-8，见 8.14）。

最终环境验证结果：Python 3.12.14 / Strawberry Perl 优先 / node v22.23.3 + grunt / git junction / cmake 3.31.6 全部命中。

8.17 v8 拉取与编译说明

fetch v8 + gclient sync -r remotes/branch-heads/8.9 拉取量大（数 GB），需代理稳定；
hooks 会自动下载 clang-format、wasm 测试数据、win_toolchain 等；
gn gen out.gn/win_64/release ... 通过后进入 ninja 编译，4 核 CPU 耗时数小时；
编译产物检查点：v8_89/v8/out.gn/win_64/release/obj/v8_monolith.lib 存在则 v8 完成，下次运行自动跳过。

9. 关键经验总结

环境版本优先于修补脚本：ONLYOFFICE 该版本只支持 VS2015/2019，新 VS 的目录布局会让老构建系统（boost 1.72 的 b2、v8 的 vs_toolchain 等）连锁失败，修补是无底洞。
产物自动跳过：boost/cef/icu/openssl/v8 均有产物检测（如 libboost_system-vc142-mt-x64-1_72.lib、v8_monolith.lib），已完成的模块重跑 make.py 时自动跳过，中断后直接重跑即可。
不要手动删 <模块>.data：会触发整体 clean + 重新下载。
depot_tools 的坑：DEPOT_TOOLS_UPDATE=0 导致自举需手动做一次；新版 bootstrap 的 Git 检测要求路径祖先中有名为 git 的目录（junction 方案可绕过）；gn.py 会剔除 venv，必须给非 venv 的 python。
cmd 的 set 陷阱：set X=Y && Z 会把空格存进变量；长命令串联易断行丢失，一律用 build.bat。
代理：HTTP_PROXY/HTTPS_PROXY 都要设（depot_tools 的 cipd 下载走 HTTPS_PROXY，git/curl 两者都可能用）。
PATH 相关组件一览（build.bat 中保证）：vcvarsall(x64) → .venv\Scripts（跑 make.py 用）+ 系统 python（供 gn）→ C:\dev-tools\git\cmd（供 depot_tools）→ scoop shims（perl、cmake 等）。
中文系统的编码坑：MSVC 工具输出 GBK、Python 构建辅助脚本按 UTF-8 解码 → decode/encode 双向崩溃。解法组合：tool_wrapper.py 一行容错（带检测标记的写法，见 8.5）+ PYTHONIOENCODING=utf-8。
scoop 新装的工具（perl/cmake/grunt-cli）必须重开窗口才进 PATH；多版本共存时用 scoop reset 切换。
CMake 必须 3.x（4.x 移除旧策略支持，详见 8.6）；grunt 需全局安装 grunt-cli（详见 8.8）。
Python 版本组合：sdkjs build.py 要求 ≥3.9（BooleanOptionalAction），v8 旧脚本限制 ≤3.12（3.13 移除 pipes）→ 选 3.9–3.12。nvm 的 node 全局包目录与激活目录不一致时，PATH 直接指向版本目录（详见 8.10）。

10. 完整环境清单与可复现配置

10.1 系统级软件

软件	版本	安装方式	备注
Visual Studio 2019 Build Tools	16.11 (MSVC v142/14.29)	官方引导程序 `aka.ms/vs/16/release/vs_buildtools.exe`	组件: VCTools.x86.x64 + Windows10SDK.19041 + DebuggingTools + .NET 4 TargetingPack
Windows SDK 10.0.19041 + 调试工具	10.0.19041.0	winsdksetup.exe (`fwlink 2120843`)	v8 只认 19041 的 Debuggers 目录
Qt	5.6.3 (msvc2015_64)	官方在线安装器 (`C:\Qt\Qt5.6.3`)	Windows 构建专用；需在 config 中 `compiler="msvc2015"` + `qt-dir="C:/Qt/Qt5.6.3/5.6.3"`
Python 3.12	3.12.14	uv 管理 (`scoop persist/uv/python/versions`)	sdkjs 要求 ≥3.9；v8 脚本 ≤3.12
Python 3.8	3.8.20	uv（.venv 内）	项目 venv
Strawberry Perl	最新	`scoop install perl`	openssl/icu 构建；PATH 必须排在 Git 自带 perl 之前
CMake	3.31.6	`scoop install cmake@3.31.6`	不可用 4.x
Node.js	v22.23.3 (nvm)	scoop nvm-windows	grunt-cli 全局装在版本目录
Git	2.56.0	scoop + junction `C:\dev-tools\git`	depot_tools 需要路径祖先中有名为 git 的目录

10.2 `build_tools/config` 关键条目

platform="win_64"
module="core builder"
branch="tags/v9.4.0.131"
vs-version="2019"
vs-path="C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build"
compiler="msvc2015"
qt-dir="C:/Qt/Qt5.6.3/5.6.3"
multiprocess="1"
sysroot="0"

（compiler 与 qt-dir 是 Windows 构建的关键：官方 Windows 路线就是 Qt 5.6.3 + MSVC。）

10.3 对 build_tools 的最小源码修改（均已实施）

文件	修改	目的
`scripts/qmake.py`（windows 分支）	追加独立 qmake 参数 `QMAKE_CXXFLAGS+=/utf-8 QMAKE_CFLAGS+=/utf-8`	强制 MSVC 以 UTF-8 解析源码，解决中文系统 GBK 误解析（见 8.14）

其余均为产物级修补（v8 重拉时需重做）：

文件	修改	目的
`core/Common/3dParty/v8_89/v8/build/toolchain/win/tool_wrapper.py`	`decode('utf8') if 0 else decode('utf8', errors='replace')`（带检测标记写法）	中文系统 link 输出 GBK 导致解码崩溃（见 8.5）

10.4 仓库级配置

仓库	配置
`core/.gitattributes`（末尾追加，已暂存）	`.cpp/.h/.c/.hpp/.pri/.pro text eol=lf`
全局	`git config core.autocrlf` 保持 true 亦可（.gitattributes 已覆盖源码类文件）

10.5 最终产物验证

core\build\bin\win_64\x2t.exe                          ← 核心转换引擎
build_tools\out\win_64\onlyoffice\core\                ← core 部署目录
build_tools\out\win_64\onlyoffice\DocumentBuilder\     ← builder 部署目录
  ├── docbuilder.c.dll / docbuilder.exe / docbuilder.py
  ├── kernel.dll / graphics.dll / doctrenderer.dll / UnicodeConverter.dll
  ├── x2t.exe / DoctRenderer.config
  └── sdkjs/ / fonts/ / dictionaries/ / empty/

10.6 已知不阻塞的残留项

项	说明
docbuilder.com.dll / docbuilder.net.dll	需完整版 VS2019 Community 的 devenv，未编（builder 主功能不受影响）
tool_wrapper.py 编码补丁	v8 重拉时会被还原，需按 8.5 重改
core 仓库若干文件的 LF 转换 modified 状态	git 行尾差异，属预期，勿还原

附：构建成功总结（终版）

2026-10：Windows (win_64) 全流程构建成功。 从 3dParty（boost/cef/icu/openssl/v8）到 js（sdkjs/web-apps）再到 core C++（Qt+MSVC）与 deploy，完整链路走通。

最终产物验证：

core\build\bin\win_64\x2t.exe 及全部工具（allfontsgen/allthemesgen/pluginsmanager/tester 等）✅
build_tools\out\win_64\onlyoffice\DocumentBuilder\：docbuilder.c.dll、docbuilder.exe、doctrenderer.dll、kernel.dll、graphics.dll、UnicodeConverter.dll、x2t.exe、sdkjs/fonts/dictionaries 等全套 ✅
与官方 document-builder PyPI 包内容对齐（win_amd64 wheel 所需 DLL 全集）✅

详细可复现配置见第 10 节。

附：历史进度记录

模块	状态
boost (1.72, vc142, win_64)	✅
cef	✅
icu	✅
openssl	✅
v8 8.9	✅
cmake / perl / node+grunt	✅
js 阶段（sdkjs/web-apps）	✅
docbuilder.com/.net	⚠️ 跳过（缺 devenv）
core 主构建（Qt+MSVC）	✅
deploy / 最终产物	✅ 完成（x2t.exe 等）

#问题记录

在 Windows 10 中编译 ONLYOFFICE 模块的踩坑记录

https://blog.cikaros.cn/archives/zai-windows-10-zhong-bian-yi-onlyoffice-mo-kuai-de-cai-keng-ji-lu

作者

Cikaros

发布于

2026年10月08日

许可协议

在 WSL2 中编译 ONLYOFFICE Core 模块的踩坑记录（续）上一篇

在 Windows 10 中编译 ONLYOFFICE 模块的踩坑记录

目录

1. 总体环境要求

必装软件清单

VS2019 Build Tools 安装方式

build_tools 配置文件（build_tools\config，无扩展名文本文件）

2. 构建入口与推荐方式（build.bat）

3. 阶段一：Boost 构建失败

现象

根因

解决

4. 阶段二：Boost b2 引擎找不到 vcvarsall

现象（换用 VS2026 编译时出现，现已放弃该路线）

根因

结论

5. 阶段三：cef 下载失败（curl 代理语法错误）

现象

根因

解决

6. 阶段四：icu 编译失败（MSB3644）

现象

根因

解决

7. 阶段五：icu 需要 Perl

现象

根因

解决

8. 阶段六：v8/depot_tools 全流程问题

8.1 python3_bin_reldir.txt not found（depot_tools 未引导）

8.2 depot_tools 找不到 Git（scoop 布局不兼容）

现象 A

现象 B

8.3 gn 找不到 python（venv 被 PruneVirtualEnv 剔除）

现象

8.4 v8 gn gen 报缺 dbghelp.dll（Windows SDK 调试工具）

现象

8.5 中文系统导致的 Python 编解码崩溃（v8 link 阶段）

现象 1：decode 崩溃

现象 2：print 崩溃（decode 修复后出现）

8.6 缺 cmake

8.7 docbuilder.com/.net 报 devenv 不是内部或外部命令

8.8 js 阶段缺 grunt

8.9 sdkjs build.py 报 argparse 无 BooleanOptionalAction（Python 版本过低）

8.10 nvm 布局导致 grunt 在 cmd 中找不到

8.11 deploy 阶段出现大量 copy warning 与 x2t 运行失败

8.12 core C++ 编译：缺 3dParty 源码（C1083 找不到头文件）

8.13 openssl Windows 构建产物为空（openssl/sha.h 找不到）

8.14 DefaultNotesTheme.cpp 报 C2059/C2017（MSVC 用 GBK 解析 UTF-8 无 BOM 源文件）

8.16 build.bat 生成（汇总）

8.17 v8 拉取与编译说明

9. 关键经验总结

10. 完整环境清单与可复现配置

10.1 系统级软件

10.2 build_tools/config 关键条目

10.3 对 build_tools 的最小源码修改（均已实施）

10.4 仓库级配置

10.5 最终产物验证

10.6 已知不阻塞的残留项

附：构建成功总结（终版）

附：历史进度记录

10.2 `build_tools/config` 关键条目