Windows 构建与发布

2.1 安装 Visual Studio

安装 Visual Studio，并选择以下工作负载：

• 使用 C++ 的桌面开发

这样会同时安装 MSVC 编译器、CMake 和 Ninja。

Community 版可免费用于个人开发和开源开发。

2.2 安装 Qt 6

# 添加到用户环境变量（Qt 的安装路径请根据实际环境修改）
# 例：C:\Qt\6.8.3\msvc2022_64
[Environment]::SetEnvironmentVariable("Qt6_DIR", "C:\Qt\6.8.3\msvc2022_64\lib\cmake\Qt6", "User")
[Environment]::SetEnvironmentVariable("PATH", "C:\Qt\6.8.3\msvc2022_64\bin;$env:PATH", "User")

pip install aqtinstall
aqt install-qt windows desktop 6.8.3 win64_msvc2022_64 -m qtcharts

2.3 安装 Ninja（推荐）

可以使用 Visual Studio 自带的 Ninja，也可以单独安装：

winget install Ninja-build.Ninja

2.4 确认安装

在 Developer PowerShell for VS 2022（从开始菜单启动）中确认：

cmake --version       # 3.16 以上
cl                    # MSVC 编译器
ninja --version       # Ninja
windeployqt --version # Qt 部署工具

构建脚本（推荐）

使用 scripts/build-windows.ps1，可以一次完成从 Release 构建到制作 ZIP 的全部步骤。

重要：请在 Developer PowerShell for VS 2022 中运行（需要 MSVC 的环境变量）。

# 普通构建 + 制作 ZIP
.\scripts\build-windows.ps1

# 清理后构建，不制作 ZIP
.\scripts\build-windows.ps1 -Clean -SkipZip

# 按版本构建到各自的目录（发布时）
.\scripts\build-windows.ps1 -BuildDir build\msvc-release-2026.10.07 `
    -DeployDir build\releases\2026.10.07-windows\deploy `
    -ZipPath build\releases\2026.10.07-windows\ShogiBoardQ-windows.zip

脚本会自动执行以下处理：

1. 确认所需工具（cmake、ninja、cl、windeployqt、MSVC 运行库 DLL 的位置）
2. CMake 配置 + 构建（ShogiBoardQ、shogiboardq-cli、Hayanagi）
3. 确认构建产物（.exe、.qm 翻译文件、hayanagi.exe 和定式文件、每种手数各 1 个文件的题集）
4. 创建 deploy 目录 + 放置题集、Hayanagi（含定式文件）和 LICENSE + 用 windeployqt 部署 DLL + 添加 qoffscreen.dll + 复制 MSVC 运行库 DLL + 校验
5. 制作 ZIP 文件

如果没有把 Qt 加入 PATH，请在运行前指定 Qt 的位置（例：Qt 6.11.2）：

$env:PATH = "C:\Qt\6.11.2\msvc2022_64\bin;C:\Qt\Tools\Ninja;$env:PATH"
$env:CMAKE_PREFIX_PATH = "C:\Qt\6.11.2\msvc2022_64"

出现执行策略错误时：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

以下是手动逐条运行命令时的步骤。

3.1 Release 构建

在 Developer PowerShell for VS 2022 中运行：

cd C:\path\to\ShogiBoardQ

# 配置（Release 构建，Ninja）
cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release

# 构建
ninja -C build

没有 Ninja 时（使用 Visual Studio 生成器）：

# 配置
cmake -B build -S .

# Release 构建
cmake --build build --config Release

3.2 确认构建产物

# 确认已生成 exe
# Ninja：
dir build\ShogiBoardQ.exe

# Visual Studio 生成器：
dir build\Release\ShogiBoardQ.exe

# 确认翻译文件
dir build\*.qm           # Ninja
dir build\Release\*.qm   # VS 生成器

3.3 运行确认

# 启动构建好的应用程序（需在 PATH 中包含 Qt DLL 的环境下）
.\build\ShogiBoardQ.exe

4.1 创建 deploy 目录

将 exe、翻译文件、诘棋题集、Hayanagi 及其定式文件和 LICENSE 复制到发布用目录：

mkdir deploy, deploy\Hayanagi\book, deploy\data\tsumeshogi
copy build\ShogiBoardQ.exe deploy\
copy build\shogiboardq-cli.exe deploy\
copy build\*.qm deploy\
copy build\Hayanagi\hayanagi.exe deploy\Hayanagi\
copy build\Hayanagi\book\hayanagi_book.db deploy\Hayanagi\book\
copy data\tsumeshogi\tsume_*ply_*.txt deploy\data\tsumeshogi\
copy LICENSE deploy\

诘棋题集收录 3、5、7、9、11、13 手诘各 1 个文件，共 6 个文件（data/tsumeshogi/ 中不能残留相同手数的旧版本；有多个时脚本会停止）。不收录 README（根目录、Hayanagi/、data/tsumeshogi/）。Hayanagi 的定式文件 hayanagi_book.db 使用构建时复制到 build/Hayanagi/book/ 的文件，放入 Hayanagi/book/。Hayanagi 从工作目录的 book/ 读取定式，而 ShogiBoardQ 以引擎所在的目录作为工作目录启动引擎，因此解压 ZIP 后即可直接使用定式。请不要整个复制源代码树或构建文件夹，并在发布前确认 ZIP 中不包含 Hayanagi/source/ 和 licenses/。普通构建生成的 build/licenses/ 也不复制到 Windows 的 ZIP 中。

4.2 用 windeployqt 部署 Qt DLL

windeployqt --release --no-translations --no-system-d3d-compiler --no-opengl-sw --no-compiler-runtime deploy\ShogiBoardQ.exe deploy\shogiboardq-cli.exe

# shogiboardq-cli 使用 offscreen 平台绘制棋盘。windeployqt 不会复制它，因此需要手动添加
copy C:\Qt\6.11.2\msvc2022_64\plugins\platforms\qoffscreen.dll deploy\platforms\

windeployqt 自动执行的处理：

1. 复制依赖的 Qt DLL（Qt6Core、Qt6Gui、Qt6Widgets、Qt6Charts、Qt6Network、Qt6Multimedia 等）
2. 复制 Qt 插件（platforms/qwindows.dll、imageformats/ 等）

4.2.1 复制 MSVC 运行库 DLL

为了在没有安装 Visual C++ 可再发行组件包的电脑上也能启动，将 MSVC 运行库 DLL（vcruntime140.dll、msvcp140.dll 等）放在与 exe 相同的目录中。在 Developer PowerShell for VS 中，环境变量 VCToolsRedistDir 指向运行库所在的位置：

copy "$env:VCToolsRedistDir\x64\Microsoft.VC*.CRT\*.dll" deploy\

Hayanagi\hayanagi.exe 只在自身所在的目录中查找 DLL，因此只把它加载的 3 个 DLL（vcruntime140.dll、vcruntime140_1.dll、msvcp140.dll）也放到 Hayanagi\ 中：

foreach ($dll in "vcruntime140.dll", "vcruntime140_1.dll", "msvcp140.dll") {
    copy "$env:VCToolsRedistDir\x64\Microsoft.VC*.CRT\$dll" deploy\Hayanagi\
}

windeployqt 默认附带的不是 DLL，而是 vc_redist.x64.exe（约 18 MB）。但除非用户手动运行它，否则运行库不会被安装，因此直接附带 DLL。

4.3 部署后的确认

# 确认目录结构
tree /F deploy

# 确认必需的 DLL
dir deploy\Qt6Core.dll
dir deploy\Qt6Gui.dll
dir deploy\Qt6Widgets.dll
dir deploy\Qt6Charts.dll
dir deploy\Qt6Network.dll

# 确认 MSVC 运行库 DLL
dir deploy\vcruntime140.dll
dir deploy\vcruntime140_1.dll
dir deploy\msvcp140.dll

# 确认 platforms 插件
dir deploy\platforms\qwindows.dll
dir deploy\platforms\qoffscreen.dll

# SQLite 驱动（用于保存诘棋的解题记录）
dir deploy\sqldrivers\qsqlite.dll

# Hayanagi、定式文件与题集（6 个文件）
dir deploy\Hayanagi
dir deploy\Hayanagi\book\hayanagi_book.db
dir deploy\data\tsumeshogi

部署后的目录结构：

deploy/
├── ShogiBoardQ.exe                ← 可执行文件
├── shogiboardq-cli.exe            ← CLI（由 MCP 服务器调用）
├── LICENSE                        ← 许可
├── ShogiBoardQ_ja_JP.qm           ← 日语翻译
├── ShogiBoardQ_en.qm              ← 英语翻译
├── ShogiBoardQ_zh_CN.qm           ← 简体中文翻译
├── ShogiBoardQ_zh_TW.qm           ← 繁体中文翻译
├── Qt6Core.dll                    ← Qt Core
├── Qt6Gui.dll                     ← Qt GUI
├── Qt6Widgets.dll                 ← Qt Widgets
├── Qt6Charts.dll                  ← Qt Charts
├── Qt6Network.dll                 ← Qt Network
├── Qt6Multimedia.dll              ← Qt Multimedia（棋子音效）
├── Qt6OpenGL.dll                  ← Qt OpenGL（Charts 依赖）
├── Qt6OpenGLWidgets.dll           ← Qt OpenGL Widgets
├── Qt6Svg.dll                     ← Qt SVG（图标用）
├── Qt6Sql.dll                     ← Qt SQL（解题记录）
├── avcodec-61.dll 等              ← FFmpeg（播放棋子音效）
├── vcruntime140.dll               ← MSVC 运行库
├── vcruntime140_1.dll
├── msvcp140.dll
├── ...                            ← 其他 MSVC 运行库 DLL（concrt140.dll 等）
├── Hayanagi/
│   ├── hayanagi.exe               ← 用于普通对局的 USI 引擎
│   ├── vcruntime140.dll           ← Hayanagi 用 MSVC 运行库（仅这 3 个）
│   ├── vcruntime140_1.dll
│   ├── msvcp140.dll
│   └── book/hayanagi_book.db      ← Hayanagi 的定式
├── data/tsumeshogi/
│   ├── tsume_3ply_1000_*.txt      ← 诘棋题集（3～13 手诘，各 1,000 题）
│   ├── ...
│   └── tsume_13ply_1000_*.txt
├── platforms/
│   ├── qwindows.dll               ← Windows 平台插件
│   └── qoffscreen.dll             ← shogiboardq-cli 绘制棋盘用
├── sqldrivers/
│   ├── qsqlite.dll                ← SQLite（诘棋的解题记录）
│   └── ...
├── multimedia/
│   ├── ffmpegmediaplugin.dll      ← 播放棋子音效
│   └── windowsmediaplugin.dll
├── imageformats/
│   ├── qsvg.dll                   ← SVG 支持
│   ├── qico.dll                   ← ICO 支持
│   └── ...
├── styles/
│   └── qmodernwindowsstyle.dll    ← Windows 样式
├── tls/
│   └── qschannelbackend.dll       ← TLS（CSA 网络通信用）
└── networkinformation/
    └── qnetworklistmanager.dll    ← 网络信息

由于附带了 MSVC 运行库 DLL，用户的电脑上无需安装 Visual C++ 可再发行组件包。

4.4 运行测试

直接从 deploy 文件夹启动进行测试：

.\deploy\ShogiBoardQ.exe

# CLI（版本与生成棋盘图片）
.\deploy\shogiboardq-cli.exe version
.\deploy\shogiboardq-cli.exe render-board --sfen startpos --output board.png --overwrite

# Hayanagi（与 ShogiBoardQ 一样在 Hayanagi 的文件夹中启动，应返回 id name Hayanagi … 和
# info string book loaded）
cmd /c "cd deploy\Hayanagi && (echo usi& echo isready& echo quit) | .\hayanagi.exe"

重要：请在 PATH 中不包含 Qt 的 bin 目录的环境下测试。如果 PATH 中包含 Qt，就会使用系统中的 DLL 而不是 deploy 文件夹中的 DLL，从而无法发现部署遗漏。

4.5 制作 ZIP 文件

Compress-Archive -Path deploy\* -DestinationPath ShogiBoardQ-windows.zip

5.1 创建标签

版本号只在发布当天改为当天的日期（版本号与发布的运用，日文）。制作发布包之前，先修改 CMakeLists.txt 中的 APP_VERSION 并提交，用该提交制作发布包，然后在同一提交上打相同版本号的标签。标签不加 v。

git tag -a 2026.10.07 -m "ShogiBoardQ 2026.10.07"
git push origin main 2026.10.07

5.2 用 GitHub CLI 创建 Release

使用 GitHub CLI (gh)：

# 安装
winget install GitHub.cli

# 登录（仅首次）
gh auth login

创建 Release 并上传附件：

gh release create 2026.10.07 `
  --title "ShogiBoardQ 2026.10.07" `
  --notes-file RELEASE_NOTES.md `
  ShogiBoardQ-windows.zip

同时发布 macOS 的 DMG 时，添加附件：

gh release create 2026.10.07 `
  --title "ShogiBoardQ 2026.10.07" `
  --notes-file RELEASE_NOTES.md `
  ShogiBoardQ-windows.zip `
  ShogiBoardQ.dmg

gh release create 2026.10.07 `
  --title "ShogiBoardQ 2026.10.07" `
  --generate-notes `
  ShogiBoardQ-windows.zip

5.3 在网页界面上创建 Release（替代方法）

1. GitHub 仓库 → Releases → Draft a new release
2. Choose a tag → 输入新标签（例：2026.10.07）并创建
3. 输入 Release title（例：ShogiBoardQ 2026.10.07）
4. 在 Description 中填写发布说明
5. 将 ShogiBoardQ-windows.zip 拖放到 Attach binaries
6. 点击 Publish release

5.4 发布说明的写法（模板）

## ShogiBoardQ 2026.10.07

### 下载

| OS | 文件 |
|---|---|
| Windows (64-bit) | `ShogiBoardQ-windows.zip` |
| macOS | `ShogiBoardQ.dmg` |

### 在 Windows 上启动

1. 解压 ZIP 文件
2. 双击 `ShogiBoardQ.exe`

> 首次启动时如果显示“Windows 已保护你的电脑”，
> 请点击“更多信息”→“仍要运行”。

### 变更内容

- ...

6.1 获取代码签名证书

代码签名推荐使用 EV（Extended Validation）代码签名证书。对个人开发者来说，OV（Organization Validation）证书也是一种选择。

主要提供商：

• SignPath Foundation（面向开源项目，免费）
• DigiCert
• Sectigo
• GlobalSign

6.2 用 signtool 签名

# 使用 Windows SDK 中的 signtool
signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 `
  /f "certificate.pfx" /p "password" `
  deploy\ShogiBoardQ.exe

6.3 不签名发布时

向用户说明以下步骤：

1. 下载后，右键单击 ZIP → 属性 → 勾选“解除锁定” → 确定
2. 解压后运行 ShogiBoardQ.exe
3. 如果显示 SmartScreen 警告，点击“更多信息”→“仍要运行”

找不到 Qt

CMake Error: Could not find a package configuration file provided by "Qt6"

明确指定 Qt 的安装路径：

cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_PREFIX_PATH="C:\Qt\6.8.3\msvc2022_64"

找不到 cl.exe

没有使用 Developer PowerShell for VS 2022 时：

# 手动设置 MSVC 环境
# Visual Studio 2022 的情况
& "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

或者从开始菜单启动 Developer PowerShell for VS 2022。

找不到 windeployqt

# 确认 Qt 的安装路径，并添加到 PATH
$env:PATH = "C:\Qt\6.8.3\msvc2022_64\bin;$env:PATH"

# 确认
windeployqt --version

应用程序无法启动（DLL 错误）

“找不到 Qt6Core.dll”等错误

1. 重新运行 windeployqt

2. 确认所有必需的 DLL 都在 deploy 目录中：

   dir deploy\Qt6Core.dll
   dir deploy\Qt6Gui.dll
   dir deploy\Qt6Widgets.dll
   dir deploy\Qt6Charts.dll
   dir deploy\Qt6Network.dll
   dir deploy\platforms\qwindows.dll

3. 缺少 MSVC 运行库时：

   • 安装 Visual C++ 可再发行组件包

Qt Charts 的 DLL 没有被部署

windeployqt 无法检测到 Qt Charts 时，手动复制：

copy "C:\Qt\6.8.3\msvc2022_64\bin\Qt6Charts.dll" deploy\
copy "C:\Qt\6.8.3\msvc2022_64\bin\Qt6OpenGL.dll" deploy\
copy "C:\Qt\6.8.3\msvc2022_64\bin\Qt6OpenGLWidgets.dll" deploy\

无法加载翻译

确认 .qm 文件与 exe 位于同一目录：

dir deploy\*.qm

没有时，从构建目录手动复制：

copy build\ShogiBoardQ_ja_JP.qm deploy\
copy build\ShogiBoardQ_en.qm deploy\
copy build\ShogiBoardQ_zh_CN.qm deploy\
copy build\ShogiBoardQ_zh_TW.qm deploy\

执行策略错误（PowerShell 脚本）

无法加载文件 ……，因为在此系统上禁止运行脚本。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

SmartScreen 警告（未签名）

向用户说明：

1. 右键单击 ZIP → 属性 → 勾选解除锁定 → 确定
2. 先解压 ZIP 再运行
3. “Windows 已保护你的电脑”→ 更多信息 → 仍要运行

下载次数增加后，SmartScreen 的信誉会提高，警告会变得不容易出现。