企业官网建设流程全解析

• 桌面应用
• 屏幕录制
• 音视频

本文是一份面向开发者的 Captura 本地构建实战指南，以官方 docs/Build.md 为骨架，结合仓库内build.cake、ApiKeys.cs、appveyor.yml等源码与配置，完整讲解从克隆仓库、配置 Imgur/YouTube API Key、准备 FFmpeg，到使用 Visual Studio 或 Cake 脚本产出可运行程序的全过程。读完本文，你将掌握 Captura 的开发环境搭建方法、API Key 的开发/生产两套注入机制，以及 Cake 构建任务链的每个环节与常用参数。

一、构建前置条件（Prerequisites）

Captura 是一个基于 .NET 的 Windows 桌面应用（WPF），源码仓库以src/Captura.sln为核心解决方案文件。本地构建需要准备以下工具链：

dotnet tool install -g Cake.Tool --version 0.32.1

此外，官方文档提示部分特性还有额外要求（如系统版本、硬件编码器支持等），对应内容可查看仓库内的 docs/System-Requirements.md。简要摘录其中与构建运行直接相关的要点：

• 操作系统：推荐 Windows 10，最低 Windows 7（Windows 7 需开启 Aero）；
• 运行时：需要安装 .NET Framework 4.7.2 Runtime；
• FFmpeg：应用启动时若检测不到 FFmpeg 会自动提示下载；
• Intel QSV / NVenc：使用 Intel QSV HEVC 编码器需要 Skylake（第 6 代）及以上处理器；NVenc 编码器需确认 GPU 处于 NVIDIA 官方支持矩阵中。

二、构建步骤总览

官方文档给出的本地构建流程分为四步：

1. 克隆仓库；
2. 配置 API Keys（Imgur / YouTube），开发期从环境变量读取，生产构建嵌入应用；
3. 下载 FFmpeg（应用内下载、官方构建或自定义构建均可）；
4. 使用 Visual Studio 或 Cake 脚本进行构建。

下面逐一展开，并结合源码说明每步背后的实现机制。

三、第一步：克隆仓库

将 Captura 仓库克隆到本地工作目录：

git clone https://gitcode.com/gh_mirrors/ca/Captura

仓库目录结构中的关键构建入口如下：

• src/Captura.sln：Visual Studio 解决方案；
• build.cake：Cake 自动化构建主脚本；
• scripts/：被 build.cake 引用的常量、版本、API Key、Chocolatey 打包等辅助脚本；
• Inno.iss：Inno Setup 安装包脚本（生成Captura-Setup.exe）。

四、第二步：配置 API Keys（开发期环境变量机制）

Captura 的上传功能依赖两个第三方平台凭据：Imgur（截图上传）与 YouTube（视频上传）。官方文档明确说明：开发期间 API Keys 从环境变量加载，生产构建时嵌入到应用内部。

4.1 开发期读取的源码实现

开发期读取逻辑位于 src/Captura.Core/ApiKeys.cs，其核心实现为：

static string Get(string Key) => Environment.GetEnvironmentVariable(Key, EnvironmentVariableTarget.User) ?? ""; public string ImgurClientId => Get("imgur_client_id"); public string ImgurSecret => Get("imgur_secret"); public string YouTubeClientId => Get("yt_client_id"); public string YouTubeClientSecret => Get("yt_client_secret");

从源码结构可以确认两点实现事实：

1. 读取目标为用户级环境变量（EnvironmentVariableTarget.User），而非进程或系统级，因此开发者在当前 Windows 用户下setx设置即可生效；
2. 未设置的变量会被兜底为空字符串（?? ""），也就是说不配置这些变量并不会导致构建失败，只是对应的 Imgur/YouTube 上传功能不可用——这解释了官方文档中 "credentials are only required if you want to upload" 的说法。

ApiKeys类实现了IImgurApiKeys与IYouTubeApiKeys两个接口，分别定义于 src/Captura.Imgur/IImgurApiKeys.cs 与 src/Captura.YouTube/IYouTubeApiKeys.cs，供对应上传模块消费。

4.2 生产构建期的嵌入机制

生产（Release）构建时，Cake 脚本会把环境变量中的真实值替换进源码，再由编译器固化进程序集。这一过程由 scripts/apikeys.cake 的EmbedApiKeys()完成：

var match = Regex.Match(ApiKeysContent, "Get\\(\"(.*)\"\\)"); // 遍历源码中所有 Get("变量名") 调用 content = content.Replace($"Get(\"{variable}\")", $"\"{EnvironmentVariable(variable)}\"");

其执行时机在 build.cake 的Setup阶段——仅当configuration == Release时才执行EmbedApiKeys()，并在Teardown阶段通过RestoreBackups()恢复被修改的ApiKeys.cs，保证工作区源码不被污染。修改前的文件会由CreateBackup备份到temp目录。

实操提示：开发期无需任何密钥即可完成 Debug 构建；只有准备产出包含上传功能的 Release 版本时，才需要设置上述三个环境变量。

五、第三步：准备 FFmpeg

Captura 的录屏与视频处理高度依赖 FFmpeg。官方文档给出了三种获取途径：

1. 应用内自动下载：运行应用时若检测不到 FFmpeg，界面会弹出下载提示（对应仓库中的 FFmpegDownloaderWindow.xaml 与 DownloadFFmpeg.cs）；
2. 从 FFmpeg 官方构建站点下载；
3. 使用自定义构建版本。

FFmpeg 的探测、日志与参数构建等逻辑集中在 src/Captura.FFmpeg/ 项目下，其中 FFmpegService.cs 负责运行时定位 FFmpeg，FFmpegArgsBuilder.cs 负责生成命令行参数。对于本地构建调试而言，最简单的方式是启动应用后按其引导完成下载，再将 FFmpeg 放置于应用可发现的位置。

六、第四步：构建

6.1 方式一：Visual Studio 直接构建

用 Visual Studio 2019+ 打开 src/Captura.sln，选择目标配置（Debug / Release）后直接生成即可。需要注意：

• 首次加载会还原 NuGet 包（解决方案内各项目如Captura.FFmpeg、Captura.NAudio、Captura.Windows等均有独立 csproj）；
• 项目统一使用 C# 8 语言版本，由 src/Directory.Build.props 中的<LangVersion>8</LangVersion>声明；
• 非 Debug 配置下，src/PostBuild.targets 中的MoveLibs目标会把*.dll移动到输出目录的lib/子目录，并将*.pdb、*.xml清理掉，形成较干净的发布结构。

6.2 方式二：Cake 脚本自动化构建

仓库以 Cake 作为统一构建编排层，核心脚本为 build.cake，常用参数如下（详见 docs/Cake.md）：

典型调用：

dotnet-cake --target=CI --configuration=Release

6.3 Cake 任务链与版本号处理

从 build.cake 的源码可以看到完整的任务依赖关系：

• Build：调用MSBuild对src/Captura.sln执行Rebuild，并指定 VS2019 工具集、自动Restore；
• Clean-Output→Populate-Output：清空dist目录后，将许可证文件（licenses）、多语言文件（Languages/*.json，来源于 src/Captura.Loc/Languages）、按键映射（keymaps）、可执行文件及lib目录汇总到dist；
• Pack-Portable：在dist内预建Settings、Codecs目录后打包为temp/Captura-Portable.zip；
• Pack-Setup：调用 Inno Setup 编译 Inno.iss，通过/DMyAppVersion={version}注入版本号，产出temp/Captura-Setup.exe；
• Pack-Choco：调用 scripts/choco.cake 生成 Chocolatey 安装包；
• Test：使用 xUnit 运行 src/Tests/Tests.csproj 生成的Captura.Tests.dll，测试用例覆盖属性存储、截图、录制、窗口枚举等核心能力；
• Default：串联Pack-Portable、Pack-Setup、Pack-Choco；
• CI：先跑Test，再执行全部打包任务。

版本号的处理逻辑位于 scripts/version.cake：HandleVersion()会用正则校验build_version参数——稳定版需匹配^v\d+\.\d+\.\d+$，预发布版匹配^v\d+\.\d+\.\d+-[^\s]+$，格式非法会直接抛出ArgumentException；随后把去掉v前缀的版本号写入src/Captura/Properties/AssemblyInfo.cs与src/Captura.Console/Properties/AssemblyInfo.cs的AssemblyVersion属性。

实操提示：build_version必须带v前缀（如v9.0.0），且不能使用build-number-开头的特殊标签（CI 会跳过此类构建）。

七、CI 构建参考（appveyor.yml）

官方使用 AppVeyor 作为持续集成平台，配置见仓库根目录的 appveyor.yml。它对本地方案具有很强的参照价值：

• 构建镜像为Visual Studio 2019，分别对Debug与Release两种配置执行 CI；
• install阶段安装 Cake.Tool 0.32.1 与 Inno Setup（choco install innosetup）；
• build_script阶段根据是否有 Git 标签决定版本号：打标签时用标签名作为--build_version，否则生成v0.0.{构建号}并执行dotnet-cake --target=CI --configuration=... --build_version=...；
• 敏感信息（imgur_client_id、yt_client_id、yt_client_secret、choco_key、git_key）通过 AppVeyor 的secure加密环境变量注入；
• 构建产物包括temp/Captura-Portable.zip、temp/Captura-Setup.exe与temp/captura.*.nupkg，标签构建时自动发布。

本地复刻这套流程时，只需保证：安装了 VS2019 工作负载与 Cake 工具、设置了上述三个 API Key 环境变量（仅 Release 需要）、准备好 Inno Setup（仅打包安装程序需要）。

八、构建排查要点小结

基于前文源码证据，将常见问题与处理思路汇总如下：

1. dotnet-cake命令找不到：确认 .NET Core 2.1+ 已安装，且dotnet tool install -g Cake.Tool --version 0.32.1执行成功（全局工具默认路径在用户目录下，需保证其加入 PATH）；
2. Release 构建提示版本格式错误：检查--build_version是否为v\d+.\d+.\d+或v\d+.\d+.\d+-<后缀>格式，参照 scripts/version.cake 的正则校验；
3. 上传功能不可用：确认imgur_client_id、yt_client_id、yt_client_secret已设置为用户级环境变量（对应 src/Captura.Core/ApiKeys.cs 的EnvironmentVariableTarget.User），设置后需重启终端/IDE 使其生效；
4. 打包目录异常：dist、temp等目录由 scripts/constants.cake 统一定义，若之前构建中断，可先执行Clean-Output任务清理dist再重试；
5. 录制相关功能异常：优先确认 FFmpeg 是否已就绪，应用内下载或手动放置均可，系统级要求参考 docs/System-Requirements.md。

至此，你已经掌握了 Captura 从零构建的完整链路：环境准备 → API Key 注入 → FFmpeg 就绪 → Visual Studio/Cake 双路径构建 → 打包与 CI 对齐，可以顺利产出 Debug 调试版本或 Release 发布版本进行二次开发与定制。

• 桌面应用
• 屏幕录制
• 音视频