Gyroflow Windows 源码环境搭建和编译运行

本文记录 Gyroflow 1.6.1 在 Windows x86_64/MSVC 环境中的依赖安装、脚本修正、Release 构建和运行验证过程。

• 构建目标：x86_64-pc-windows-msvc
• 最终状态：Release 构建成功，运行期冒烟测试成功
• 可执行文件：target\release\gyroflow.exe

1. 项目和构建组成

Gyroflow 是使用陀螺仪数据进行视频稳定的跨平台应用。当前源码版本为 1.6.1，主要组成如下：

• Rust：应用逻辑、稳定算法、渲染控制和 GPU 计算；
• Qt 6/QML：桌面图形界面；
• FFmpeg：视频编解码、封装和滤镜；
• OpenCV：镜头标定、光流和同步辅助；
• OpenCL/wgpu/Qt RHI：GPU 加速；
• MDK SDK：视频预览和媒体播放；
• MSVC/Windows SDK：Windows 原生 C/C++ 编译和链接。

2. 缓存 盘目录策略

所有可控的下载、环境、缓存、临时文件和构建输出均位于项目所在盘：

安装完成后的实测占用：

• ext：约 7.00 GB，47,897 个文件；
• target：约 4.79 GB，12,635 个文件；
• 总计约 11.79 GB，不包含项目需提前安装的 Rust、Visual Studio、Windows SDK 和 Python。

3. 基础工具环境

基础环境：

4. 安装后的依赖版本

5. 对原安装脚本的修正

修改了 _scripts/common.just 和 _scripts/windows.just，主要修正如下。

5.1 移除危险删除

原脚本存在以下风险：

• 使用 rm -Recurse -Force \vcpkg，可能解析为当前盘符根目录的 D:\vcpkg；
• 强制删除 C:\Program Files (x86)\Windows Kits\10 中的 10.0.26100 SDK 目录。

修正后：

• 不再删除任何 Windows SDK；
• 只有在 ext\vcpkg 是残缺目录且没有 .git 时才允许清理；
• 删除前会解析绝对路径并验证目标严格位于本项目 ext 内；
• 正常的 vcpkg 构建缓存不再在安装成功后删除。

5.2 临时目录

脚本现在导出以下环境变量：

TEMP=<project>\ext\.tmp
TMP=<project>\ext\.tmp
PIP_CACHE_DIR=<project>\ext\.cache\pip
VCPKG_DOWNLOADS=<project>\ext\.cache\vcpkg-downloads
VCPKG_DEFAULT_BINARY_CACHE=<project>\ext\.cache\vcpkg-archives
MDK_SDK=<project>\ext\mdk-sdk

5.3 使用项目内 Python 环境

• 创建 ext\.venv，不向全局 Python 安装 aqtinstall；
• 实际执行候选 Python 进行验证，避免误用 Windows Store 的失效 python3.exe 命令垫片；
• 要求 Python 3.8 或更高版本；
• pip 和 aqtinstall 均安装在 D 盘项目虚拟环境中。

5.4 代理兼容

本机 Windows 代理为 127.0.0.1:7897。Python urllib 会把无协议的 HTTPS 代理错误解释成 https://127.0.0.1:7897，从而报错：

ValueError: check_hostname requires server_hostname

脚本现在会：

1. 优先使用已经设置的 HTTP_PROXY/HTTPS_PROXY；
2. 其次使用可选的 GYROFLOW_PROXY；
3. 最后读取 Windows 当前用户代理；
4. 对无协议的本地代理补充 http://，供 pip、aqt、curl 和 vcpkg 使用。

如果以后代理端口变化，可在执行前设置：

$env:GYROFLOW_PROXY = 'http://127.0.0.1:新端口'
$env:HTTP_PROXY = $env:GYROFLOW_PROXY
$env:HTTPS_PROXY = $env:GYROFLOW_PROXY

5.5 下载与压缩包校验

原脚本使用的 master.dl.sourceforge.net?...viasf=1 在本机返回 HTML 页面而不是压缩包。脚本现在改用 SourceForge 的下载入口并增加：

• curl 跟随重定向；
• HTTP 失败重试；
• .partial 临时文件和原子移动；
• 最小文件大小检查；
• 7z t 压缩包完整性检查；
• 每次解压后的关键文件检查；
• 仅在成功后删除下载压缩包。

FFmpeg 下载入口：

https://downloads.sourceforge.net/project/avbuild/windows-desktop/ffmpeg-7.1-windows-desktop-clang-gpl-lite.tar.xz?download=1

MDK SDK 下载入口：

https://downloads.sourceforge.net/project/mdk-sdk/nightly/mdk-sdk-windows-desktop-clang.7z?download=1

MDK SDK 被提前安装并通过带尾部 / 的 MDK_SDK 传给 qml-video-rs，避免其 build.rs 使用旧 SourceForge 链接进行无超时下载。尾部分隔符不能省略，因为该依赖会直接拼接 include/ 和 lib/...。

6. 从当前机器重新搭建

打开普通 PowerShell，进入项目目录：

Set-Location 'D:\workroom\rust\gyroflow\gyroflow-compare\gyroflow-master-rust'
New-Item -ItemType Directory -Force '.\ext\.tmp' | Out-Null
$env:TEMP = (Resolve-Path '.\ext\.tmp').Path
$env:TMP = $env:TEMP

如果启用了本地代理，建议同时显式设置，Cargo 首次获取 Git 依赖时也可复用：

$env:HTTP_PROXY = 'http://127.0.0.1:7897'
$env:HTTPS_PROXY = $env:HTTP_PROXY
$env:GYROFLOW_PROXY = $env:HTTP_PROXY

安装全部原生依赖：

just install-deps

脚本是幂等的，已经通过关键文件检查的依赖会跳过。安装完成后可检查 Just 最终解析的路径：

just -f .\_scripts\windows.just --evaluate |
    Select-String 'QMAKE|FFMPEG_DIR|MDK_SDK|OPENCV_LINK_PATHS|LIBCLANG_PATH|TEMP|TMP'

关键文件应存在：

Test-Path '.\ext\6.7.3\msvc2019_64\bin\qmake.exe'
Test-Path '.\ext\ffmpeg-7.1-windows-desktop-clang-gpl-lite\lib\x64\avcodec.lib'
Test-Path '.\ext\mdk-sdk\lib\x64\mdk.lib'
Test-Path '.\ext\vcpkg\installed\x64-windows\lib\opencv_core4.lib'
Test-Path '.\ext\vcpkg\installed\x64-windows\lib\OpenCL.lib'
Test-Path '.\ext\llvm\bin\libclang.dll'

7. 编译命令

Release 构建：

just build

Debug 构建：

just build-debug

Release 运行：

just run

不要直接双击 target\release\gyroflow.exe 作为日常开发启动方式，因为未打包构建依赖 Qt、FFmpeg 和 OpenCV DLL 搜索路径。just run 会自动配置这些路径。需要生成可分发目录时使用项目的 just deploy 流程；本次只验证了编译和开发运行路径，没有验证商店签名或 MSIX 发布流程。

8. 本次实测结果

8.1 核心库

命令：

cargo check --manifest-path .\src\core\Cargo.toml --locked

结果：成功，耗时约 1 分 20 秒，仅有 3 条源码 warning。

8.2 完整 Release

命令：

just build

结果：

Finished `release` profile [optimized] target(s) in 3m 51s

该时间是依赖已部分编译后的最终成功续编时间；完全清理后的首次构建会更久。

输出：

第二次增量 just build：

Finished `release` profile [optimized] target(s) in 2.18s

8.3 Debug 构建修复与验证

首次执行 just build-debug 时，qml-video-rs 报错：

fatal error C1083: Cannot open include file: 'mdk/Player.h': No such file or directory

日志中的实际错误路径为：

ext/mdk-sdkinclude/
ext/mdk-sdklib/x64/

根因是 qml-video-rs build.rs 将 MDK_SDK 与 include/、lib/x64/ 直接做字符串拼接，没有主动加入路径分隔符。修正方式是让 _scripts/common.just 导出的 MDK_SDK 始终以 / 结尾，并在安装时同时校验：

ext/mdk-sdk/include/mdk/Player.h
ext/mdk-sdk/lib/x64/mdk.lib

修复后实测：

Finished `dev` profile [unoptimized + debuginfo] target(s) in 1m 06s

• 第二次增量 just build-debug：2.05 秒；
• target\debug\gyroflow.exe：84,029,952 bytes；
• Debug gyroflow.exe --version 冒烟测试退出码：0。

8.4 运行期冒烟测试

在包含 Qt、FFmpeg、OpenCV 和 Release 输出目录的 PATH 下，以隐藏窗口执行：

target\release\gyroflow.exe --version

进程正常结束，退出码为 0。MDK 运行时成功加载并报告版本 0.35.1，说明主要动态库搜索路径有效。

8.5 幂等安装验证

依赖全部存在后再次执行：

just install-deps

结果：成功，耗时约 0.90 秒，没有重复下载或重新构建依赖。

9. 当前 warning

构建成功但存在非阻塞 warning，主要包括：

• gyroflow-core 中不必要的括号、mut 和未使用变量；
• tempfile::TempDir::into_path 已弃用；
• FFmpeg Dictionary 返回类型的生命周期写法提示。

这些 warning 不属于环境缺失，也没有阻止生成或运行可执行文件。本次没有自动修改业务源码。

10. 常用诊断

检查 Qt：

.\ext\6.7.3\msvc2019_64\bin\qmake.exe -v

检查 LLVM：

.\ext\llvm\bin\clang.exe --version

检查 vcpkg 包：

.\ext\vcpkg\vcpkg.exe list

检查完整应用的 Debug 构建链：

just build-debug

如果代理失效，先确认本地代理进程和端口，再更新 HTTP_PROXY、HTTPS_PROXY 或 GYROFLOW_PROXY。如果下载中断，直接重新执行 just install-deps；脚本会复用完整依赖和有效缓存。