OpenToonz Windows 构建全指南：基于 Visual Studio 2019 与 Qt 5.15 的源码编译、运行部署与 32 位 srv 服务生成

OpenToonz Windows 构建全指南：基于 Visual Studio 2019 与 Qt 5.15 的源码编译、运行部署与 32 位 srv 服务生成

【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz

导读

本文以 OpenToonz 官方 Windows 构建文档为核心，系统讲解在 Windows 平台上从源码编译 OpenToonz 的完整流程：从 Visual Studio 2019 与 Qt 5.15 的环境准备、Git LFS 大文件拉取、CMake 工程生成、第三方库头文件配置，到 64 位主程序构建、运行环境部署、可选 Canon 相机支持，以及用于 mov 等 QuickTime 格式解码的 32 位srv文件夹生成与翻译文件编译。读完本文，你将能够独立在 Windows 上构建出一套可运行的 OpenToonz 开发环境，并理解构建系统（toonz/sources/CMakeLists.txt）中各个选项与路径的真实含义。

一、构建环境与版本前提

根据官方文档 doc/how_to_build_win_ja.md 的说明，Windows 版 OpenToonz 已确认可在Visual Studio 2019（2015 及以上亦可）与Qt 5.15的组合下完成构建。这是本项目在 Windows 上的标准构建基线，后续所有步骤均以此为前提。

需要的软件如下：

从源码结构看，顶层构建脚本 toonz/sources/CMakeLists.txt 会依据编译器环境自动区分构建环境：在 Windows 下走BUILD_ENV_MSVC分支（toonz/sources/CMakeLists.txt#L44-L49），并要求 C++17 标准（toonz/sources/CMakeLists.txt#L6-L7），这正是 VS2019 所默认支持的标准，与官方文档的版本要求相互印证。

二、获取源码与 Git 行尾转换（UTF-8 无 BOM 的坑）

首先将本仓库克隆到本地：

git clone <仓库地址>

文档中以$opentoonz表示本仓库的根目录，下文沿用这一约定。

为什么必须处理换行符（CRLF）

官方文档特别提醒：Visual Studio 无法正确识别不带 BOM 的 UTF-8 源码。当源码文件的换行符为 LF、且单行注释（//）以日文（或其他多字节字符）结尾时，编译器会忽略换行，导致下一行也被当作注释处理，引发难以排查的编译错误。

解决办法是在克隆前对 Git 做如下配置，让 Git 在检出时将换行符转换为 CRLF：

git config core.safecrlf true

core.safecrlf会在文件「LF ↔ CRLF」往返转换不一致时发出警告，避免数据被意外改写。

三、大型依赖库的安装

体积较大的库并未包含在仓库内，需要单独安装。仓库内thirdparty/目录下保留了 gl�ut、glew、libmypaint 等小型库的源码与预编译产物（如 thirdparty/glut/3.7.6/lib、thirdparty/glew/glew-1.9.0/bin），而 Qt、OpenCV、boost 等大型依赖则需要你手动准备。

1. Git LFS：拉取lib与dll文件

lib与dll文件由 Git Large File Storage 管理。请先安装 LFS 客户端，然后在git clone之后执行：

git lfs pull

该命令会把仓库中 LFS 指针指向的实际二进制文件（如各第三方库的.lib/.dll）下载到本地。

2. Qt 5.15（64 位版）

Qt 是 OpenToonz 的跨平台 GUI 框架。从 Qt 官网（https://www.qt.io/download-open-source/）下载 Qt Online Installer（Qt Online Installer for Windows），将Qt 5.15（64 位版）安装到任意目录。

构建系统对 Qt 的定位有硬性检查。在 MSVC 环境下，toonz/sources/CMakeLists.txt#L170-L176 的逻辑是：

• 若未显式指定QT_PATH，默认尝试C:/Qt/5.15.2/msvc2019_64（64 位构建，变量为msvc2019${PLATFORM2}）；
• 若该路径不存在，则直接以FATAL_ERROR中止并提示"QT_PATH not found: ${QT_PATH}. Specify QT_PATH properly."——这就是文档中提到的Specify QT_PATH properly错误的来源。

随后构建系统要求找到的 Qt 模块包括 Core、Gui、Network、OpenGL、Svg、Xml、Script、Widgets、PrintSupport、LinguistTools、Multimedia、MultimediaWidgets、SerialPort、UiTools 等（toonz/sources/CMakeLists.txt#L284-L299），并校验最低版本 Qt 5.5.0（toonz/sources/CMakeLists.txt#L306-L311）。

3. WinTab 支持的定制版 Qt 5.15.2（可选但推荐）

官方文档指出：Qt 从 5.12 起原生改用 Windows Ink API 处理数位板输入，而 5.9 及之前使用的 WinTab API 与之行为不同，已有多起由此引发的数位板兼容性问题报告。

为此，项目维护者分发了一款将官方在 Qt 6.0 才引入的「切换回 WinTab API」功能 cherry-pick 到 5.15.2 的定制版 Qt。该定制版提供了面向 MSVC2019-x64 的预编译包（发布页为 https://github.com/shun-iwasawa/qt5/releases/tag/v5.15.2_wintab）。使用该 Qt 后，还需在 CMake 中启用：

WITH_WINTAB=ON

从源码看，WITH_WINTAB选项定义于 toonz/sources/CMakeLists.txt#L110，且只有在Windows 目标 + 64 位平台时才会真正生效：位于 toonz/sources/toonz/CMakeLists.txt#L503-L505 的代码if (WITH_WINTAB AND BUILD_TARGET_WIN AND (PLATFORM EQUAL 64))才会追加-DWITH_WINTAB宏定义。该宏在源码中的实际消费点包括数位板初始化逻辑（toonz/sources/toonz/main.cpp#L732-L734）与偏好设置项（toonz/sources/toonzlib/preferences.cpp#L701、toonz/sources/include/toonz/preferencesitemids.h#L215），后者表示该设置项仅在定义了WITH_WINTAB时才会显示。

4. OpenCV（v4.1.0 及以上）

从 https://opencv.org/ 获取 OpenCVv4.1.0 或更高版本。构建时通过以下两种方式之一告诉 CMake OpenCV 的位置：

• 在 CMake GUI 中设置OpenCV_DIR变量；
• 设置环境变量OpenCV_DIR。

OpenCV_DIR的值应指向 OpenCV 安装目录下的build文件夹，例如C:/opencv/build。

源码层面，64 位平台在 Windows 上执行find_package(OpenCV 4.1 REQUIRED)（toonz/sources/CMakeLists.txt#L331），即版本下限被硬编码为 4.1；若找不到会直接报错。OpenCV 会作为EXTRA_LIBS的一部分链接进OpenToonz主程序（toonz/sources/toonz/CMakeLists.txt#L529）。

5. Boost

从 http://www.boost.org/users/history/version_1_73_0.html 下载boost_1_73_0.zip，解压后将该文件夹复制到$opentoonz/thirdparty/boost。

文档原文此处写作「将boost_1_61_0复制到$opentoonz/thirdparty/boost」，结合上下文「下载 boost_1_73_0.zip」，应理解为解压后的 boost 目录（原文疑似笔误）。从构建脚本看，toonz/sources/CMakeLists.txt#L596-L605 实际会按boost_1_89_0、boost_1_87_0、boost_1_86_0、boost_1_85_0、boost_1_75_0、boost_1_74_0、boost_1_73_0、boost_1_72_0等多个版本目录名在thirdparty下搜索，并最终要求find_package(Boost 1.55 REQUIRED)。

四、使用 CMake 生成 Visual Studio 工程

启动 CMake GUI，按以下步骤配置：

1. Where is the source code：填写$opentoonz/toonz/sources
2. Where to build the binaries：填写$opentoonz/toonz/build
   • 也可以放在其他位置；
   • 若放在检出目录内，建议以build开头命名——仓库的 .gitignore 第 11 行的build*规则会将其忽略，避免污染 Git 工作区；
   • 若更改了构建输出目录，请相应替换下文中的路径。
3. 点击Configure，选择生成器Visual Studio 16 2019 Win64
4. 若 Qt 未安装在默认位置，会报错Specify QT_PATH properly，此时将QT_PATH设为 Qt5 的实际安装路径（例如C:/Qt/5.15.2/msvc2019_64，即上文源码中默认尝试的路径）
5. 点击Generate

生成完毕后，如果之后修改了CMakeLists.txt，构建时 CMake 会自动重新运行，无需再手动打开 CMake GUI。

值得留意的是，MSVC 分支会把所有运行时产物（exe 与 dll）统一输出到构建根目录（CMAKE_RUNTIME_OUTPUT_DIRECTORY被设为${CMAKE_BINARY_DIR}，见 toonz/sources/CMakeLists.txt#L625-L628），这正是下文「$opentoonz/toonz/build/Release中生成文件」的原因。

五、第三方库头文件配置（VC 专用）

由于 Visual C++ 与 Unix 环境的配置宏不同，构建前需要复制以下 4 个头文件（均为「VC 专用配置」覆盖「默认配置」）：

$opentoonz/thirdparty/LibJPEG/jpeg-9/jconfig.vc → $opentoonz/thirdparty/LibJPEG/jpeg-9/jconfig.h $opentoonz/thirdparty/tiff-4.0.3/libtiff/tif_config.vc.h → $opentoonz/thirdparty/tiff-4.0.3/libtiff/tif_config.h $opentoonz/thirdparty/tiff-4.0.3/libtiff/tiffconf.vc.h → $opentoonz/thirdparty/tiff-4.0.3/libtiff/tiffconf.h $opentoonz/thirdparty/libpng-1.6.21/scripts/pnglibconf.h.prebuilt → $opentoonz/thirdparty/libpng-1.6.21/pnglibconf.h

其中 jpeg 库在仓库中对应目录为 thirdparty/libjpeg-turbo（预编译头文件位于 thirdparty/libjpeg-turbo/include），tiff、libpng 的源码与预编译库分别位于 thirdparty/tiff-4.0.3 与 thirdparty/libpng-1.6.21。

补充：当前版本的 CMake 脚本（toonz/sources/CMakeLists.txt#L153-L166）在 MSVC 环境下也会在 Configure 阶段自动完成 tiff 与 libpng 这三个头文件的复制（pnglibconf.h.prebuilt、tif_config.vc.h、tiffconf.vc.h），即「配置第三方库」一步在较新版本中已被 CMake 接管。若你使用的版本仍要求手动复制，按上表执行即可。

六、64 位版主程序构建

1. 打开$opentoonz/toonz/build/OpenToonz.sln
2. 选择Release配置，执行构建
3. 构建产物生成于$opentoonz/toonz/build/Release

由于上一节提到的输出目录设置，exe 与各 dll（tnzcore、tnzbase、toonzlib、image 等）会被放在同一目录下，方便直接部署运行。

七、可选：启用 Canon 数码相机支持

若需要在 OpenToonz 中直接控制 Canon 数码相机（停格动画工作流常用），需要额外准备：

• Canon EOS Digital SDK（EDSDK）：获取方式参见佳能官网的开发者 API 页面。

然后在 CMake 中启用：

WITH_CANON=ON

从源码看，WITH_CANON选项定义于 toonz/sources/CMakeLists.txt#L108，默认 OFF。启用后：

• 主程序会追加-DWITH_CANON宏（toonz/sources/toonz/CMakeLists.txt#L499-L501）；
• 64 位构建会引入EDSDK.lib并链接 EDSDK（toonz/sources/CMakeLists.txt#L400-L404、toonz/sources/toonz/CMakeLists.txt#L530-L532）；
• 宏的消费集中在停格动画模块 toonz/sources/stopmotion（如 toonz/sources/stopmotion/canon.cpp、toonz/sources/stopmotion/stopmotioncontroller.cpp）以及相机菜单项（toonz/sources/toonz/sceneviewer.cpp#L1745、toonz/sources/toonz/mainwindow.cpp#L3603）。

运行时，将 Canon EDSDK 的.dll文件复制到OpenToonz.exe所在的同一文件夹。

八、运行环境部署

构建完成后，需要把可执行文件与依赖库组装成一个可运行的发布目录：

1. 将$opentoonz/toonz/build/Release中的内容复制到任意发布文件夹
2. 以OpenToonz.exe的路径为参数，运行 Qt 自带的windeployqt.exe：

   windeployqt.exe <发布文件夹>/OpenToonz.exe

   该命令会把运行所需的 Qt 库（Core、Gui、Widgets 等）自动收集到OpenToonz.exe同目录

3. 再将以下文件复制到OpenToonz.exe同目录：
   • $opentoonz/thirdparty/glut/3.7.6/lib/glut64.dll
   • $opentoonz/thirdparty/glew/glew-1.9.0/bin/64bit/glew32.dll
   • $opentoonz/thirdparty/libmypaint/dist/64/*.dll（即 thirdparty/libmypaint/dist/64 下的全部 dll，如 libmypaint-1-4-0.dll、libiconv-2.dll 等）
   • OpenCV、libjpeg-turbo 的.dll文件
4. 将二进制版 OpenToonz 安装目录中的srv文件夹复制到OpenToonz.exe同目录
   • 没有srv，OpenToonz 也能运行，但无法处理 mov 等 QuickTime 格式；
   • srv内文件的生成方法见后文「十」。

上述 dll 路径均已在仓库中确认存在：glut64.dll 位于 thirdparty/glut/3.7.6/lib，glew32.dll 位于 thirdparty/glew/glew-1.9.0/bin/64bit。

九、Stuff 文件夹与注册表键

如果机器上已经安装过二进制版 OpenToonz，下述两步（Stuff 复制与注册表键）通常已自动完成，可跳过。

1. 复制 Stuff 文件夹：将$opentoonz/stuff复制到任意位置
2. 创建注册表键：在注册表编辑器中创建如下键，并把值设为上一步中 stuff 文件夹的路径：

   HKEY_LOCAL_MACHINE\SOFTWARE\OpenToonz\OpenToonz\TOONZROOT

   OpenToonz 通过该注册表键定位素材库（画笔、样式、着色板、布局等，见 stuff/config 与 stuff/library）等运行资源。

完成后直接运行OpenToonz.exe，能正常启动即代表构建成功。

十、srv文件夹内文件的生成（32 位构建 + QuickTime SDK）

为什么需要 32 位进程

OpenToonz 使用 QuickTime SDK 支持 mov 等格式，而QuickTime SDK 只有 32 位版本。因此项目将 QuickTime SDK 内嵌进一个名为t32bitsrv.exe的 32 位辅助进程，64 位版 OpenToonz 通过它间接调用 QuickTime 功能。从源码看，t32bitsrv是独立的小型可执行目标（toonz/sources/t32bitsrv/CMakeLists.txt），依赖Qt5::Core、Qt5::Network、tnzcore、image；且顶层 CMake 只在32 位平台 + MSVC/Apple条件下才加入该子目录（toonz/sources/CMakeLists.txt#L763-L765）。同时，32 位构建会链接 QuickTime 的QTMLClient.lib（toonz/sources/CMakeLists.txt#L394-L396）。

以下步骤在生成srv内容的同时，也会构建出一个 32 位版 OpenToonz。

1. 安装 32 位版 Qt

使用与 64 位版相同的 Qt 安装器，额外安装Qt 5.x（32 位版）到任意目录（例如C:/Qt/5.15.2/msvc2019）。

2. 获取 QuickTime SDK

1. 注册 Apple 开发者账号后，从 Apple 下载页面搜索下载QuickTime 7.3 SDK for Windows.zip
2. 安装 QuickTime SDK，将C:\Program Files (x86)\QuickTime SDK中的内容复制到：

   $opentoonz/thirdparty/quicktime/QT73SDK

   仓库中该目录当前为空的占位（见 thirdparty/quicktime/QT73SDK 与 thirdparty/quicktime/copy_QT73SDK.txt），需自行填充 SDK 文件。

3. 生成 32 位 Visual Studio 工程

步骤与 64 位版相同，仅替换以下参数：

• 构建目录：$opentoonz/toonz/build→$opentoonz/toonz/build32
• 生成器：Visual Studio 16 2019x64→ Visual Studio 16 2019Win32
• QT_PATH：指向 32 位版 Qt 的安装路径

4. 构建 32 位版

打开并构建：

$opentoonz/toonz/build32/OpenToonz.sln

5. 组装srv文件夹

在 64 位版的srv文件夹中放入以下文件：

十一、翻译文件（.ts / .qm）的生成

OpenToonz 的界面翻译遵循 Qt 标准流程：

1. 从源码提取可翻译文本，生成.ts文件；
2. 对.ts文件进行人工翻译；
3. 由.ts编译生成.qm文件（运行时实际加载的格式）。

在 Visual Studio 解决方案中，存在多个以translation_开头的工程（如translation_toonz、translation_toonzqt、translation_tnztools等）。只构建translation_???工程（在解决方案资源管理器中右键选择「仅生成…」），即可一次性生成.ts与.qm文件。这些工程被标记为不参与解决方案的整体构建（EXCLUDE_FROM_DEFAULT_BUILD TRUE），因此正常 Build 不会触发翻译流程。

从源码看，翻译工程由add_translation()函数动态生成（toonz/sources/CMakeLists.txt#L679-L695），为每个模块创建translate_update_${module}自定义目标；支持的语言代码列表定义于 toonz/sources/CMakeLists.txt#L662-L664（japanese、italian、french、spanish、chinese、german、russian、korean、czech、portuguese_brazil），对应的.ts源文件按语言分目录存放于 toonz/sources/translations。随后add_compile_translations_command()（toonz/sources/CMakeLists.txt#L700-L729）会在主工程构建后自动调用lrelease，把.ts编译为.qm并输出到stuff/config/loc/<语言显示名>/目录，供运行时加载。

十二、常见问题与排错提示

• Specify QT_PATH properly错误：说明 Qt 未安装到默认路径。默认路径在 MSVC 下为C:/Qt/5.15.2/msvc2019_64（64 位）与C:/Qt/5.15.2/msvc2019（32 位），请在 CMake 中显式设置QT_PATH指向实际安装目录。
• OpenCV 找不到：确认版本 ≥ 4.1.0，并确保OpenCV_DIR指向 OpenCV 安装目录下的build文件夹。
• jconfig.h/tif_config.h/tiffconf.h/pnglibconf.h缺失：按「五、第三方库头文件配置」复制对应的.vc或.prebuilt版本；新版 CMake 也会在 Configure 阶段自动处理。
• mov 文件无法导入/导出：srv文件夹缺失或未正确放置，需要按「十、srv 文件夹生成」完成 32 位构建并部署。
• 日文注释导致的诡异编译错误：确认core.safecrlf true已配置且源码以 CRLF 检出，规避 MSVC 对无 BOM UTF-8 的解析问题。
• 数位板行为异常：若使用 Qt ≥ 5.12 的 Windows Ink 行为与预期不符，可换用 WinTab 定制版 Qt 5.15.2，并在 CMake 中启用WITH_WINTAB=ON（仅 64 位构建生效）。

至此，从环境准备、依赖安装、CMake 配置、双平台（64 位主程序 + 32 位srv）构建到运行部署与翻译编译，Windows 上 OpenToonz 的完整构建链路已全部打通。

【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz