PowerToys 开发者文档全指南：从零搭建 Windows 工具集开发环境到构建、调试与打包

PowerToys 开发者文档全指南从零搭建 Windows 工具集开发环境到构建、调试与打包【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToysPowerToys 是微软开源的一套 Windows 生产力工具集合当前仓库根目录见 README.md包含 FancyZones、PowerRename、PowerToys Run、键盘管理器等数十个模块。本文以仓库中面向开发者的总入口文档 doc/devdocs/readme.md 为骨架系统梳理贡献者与二次开发者从「获取代码 → 一键配置环境 → 构建 → 调试 → 新增模块 → 提交 PR → 打包安装器」的完整路径并结合仓库内的构建脚本、.vsconfig与 WinGet 配置源码逐项验证帮助你在本地把整套工具集跑起来并参与到迭代中。一、文档体系与开发入口仓库在doc/devdocs/下维护了一份面向开发者的完整文档树doc/devdocs/readme.md 是这份文档的总入口按「起步Getting Started」「开发规范Development Guidelines」「协作规则Rules」「GitHub 工作流」「核心架构Core Architecture」「公共组件Common Components」「工具Tools」「流程Processes」等板块组织直接对应到仓库的三大类工程原生 C/WinUI 工程由 PowerToys.slnx 统一管理涵盖 runner托盘主进程、各个原生模块与安装器托管 .NET 工程如 Settings UI、若干 C# 模块分布在src/下打包与部署工程installer/下的 BootstrapperEXE与 MSIWiX工程。建议按本指南顺序先打通「构建 → 运行 → 调试」最小闭环再结合 创建新 PowerToy 指南 深入模块开发。二、前置条件Prerequisites原文档明确列出的系统级要求如下这是能否成功编译的前提操作系统Windows 10 April 2018 Update版本 1803或更高版本Visual Studio推荐 VS 2026或 Visual Studio 2022 17.4且必须安装以下工作负载/组件使用 C 的桌面开发Desktop Development with CWinUI 应用程序开发.NET 桌面开发Windows 11 SDK10.0.22621.0Windows 11 SDK10.0.26100.3916.NET 8 SDKWindows 长路径支持开启后避免源码树深路径导致编译失败。这些组件并非随手可选仓库根目录的 .vsconfig 文件精确记录了 PowerToys 构建所需的 VS 组件清单其中不仅包含上述工作负载还列出了Microsoft.VisualStudio.Component.VC.ATL含 ARM64/Spectre 变体、Microsoft.VisualStudio.Component.Vcpkg、WindowsAppSdkSupport.CSharp/Cpp等关键项。你可以直接让 Visual Studio Installer 导入该文件比手动勾选更可靠。小贴士来自原文档仓库在 .config 目录下提供了 WinGet 配置文件可用一条命令自动安装全部 VS 工作负载winget configure .config\configuration.winget按你的 VS 版本选择对应文件例如.config\configuration.vsProfessional.wingetVS Professional或.config\configuration.vsEnterprise.wingetVS Enterprise。从仓库内容看这一「一键装环境」不只是口头建议——.config/configuration.winget 是一个基于 WinGet ConfigurationDSC的真实可执行配置它依次声明「启用开发者模式WindowsSettings 资源elevated」「通过 winget 源安装 Visual Studio CommunityWinGetPackage 资源」「随后用 VSComponents 资源加载仓库根目录的 .vsconfig 完成组件安装」并在文件尾部明确提示下一步手动执行git submodule update --init --recursive。也就是说WinGet 配置负责解决工具链子模块仍由 Git 层完成。三、获取代码Fork、Clone 与子模块初始化原文档给出的标准协作流程是在 GitHub 上 Fork 本仓库将你自己的 Fork Clone 到本地运行仓库自带的自动化环境配置脚本推荐.\tools\build\setup-dev-environment.ps1setup-dev-environment.ps1 到底做了什么我阅读了 tools/build/setup-dev-environment.ps1 的完整实现脚本会按顺序执行 4 步并且幂等、可重复运行启用 Windows 长路径通过写注册表项HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem的LongPathsEnabled 1实现需要管理员权限启用 Windows 开发者模式通过写注册表项HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock的AllowDevelopmentWithoutDevLicense 1实现需要管理员权限安装 .vsconfig 中要求的 VS 组件使用本机 Visual Studio Installer 接口按组件清单补齐工作负载初始化 git 子模块执行git submodule update --init --recursive。脚本支持-Help查看全部参数。从参数定义tools/build/setup-dev-environment.ps1可以看到可跳过任一步骤的开关-SkipLongPaths、-SkipDevMode、-SkipVSComponents、-SkipSubmodules以及自定义 VS 安装路径的-VSInstallPath。原文档的 PowerShell 注释进一步说明非管理员运行时脚本会在涉及注册表/组件安装的步骤自动触发 UAC 提权仓库根目录通过向上查找PowerToys.slnx自动定位因此可以从任意子目录调用。手动搭建的替代路径若不想用脚本原文档也提供了折叠起来的手动流程用 Visual Studio 打开根目录的PowerToys.slnx若解决方案资源管理器弹出「install extra components」对话框点击 install或在 Visual Studio Installer 中导入仓库根目录的 .vsconfig 自动安装全部工作负载手动初始化子模块一次性步骤绝大多数工程编译前必须执行git submodule update --init --recursive代码中很多跨仓库依赖如 Monaco、外部组件都以 git submodule 形式挂接跳过此步会导致大量工程无法还原 NuGet/vcpkg 依赖这是新手最常见的构建失败原因。四、编译 PowerToysVisual Studio 与命令行双路径原文档提供了两种构建方式均以仓库根目录的解决方案文件 PowerToys.slnx 为编译入口。方式一Visual Studio IDE用 VS 打开PowerToys.slnx在顶部「解决方案配置」下拉框中选择Release或Debug从「生成」菜单选择「生成解决方案」或直接按CtrlShiftB首次完整编译通常需要数分钟取决于机器性能完成后产物位于仓库下的x64\Release\目录。需要注意的模块可用性边界原文档明确提醒编译完成后可直接运行x64\Release\PowerToys.exe而无需安装 PowerToys但部分模块如 PowerRename、ImageResizer、文件资源管理器扩展等必须额外构建并安装 installer 后才能生效。这是因为这些能力依赖外壳扩展注册与 MSIX/WiX 部署流程光跑主程序并不会把它们注册进系统。方式二命令行构建脚本仓库在 tools/build/ 下集中了构建工具链核心脚本与用法如下# 构建完整解决方案自动探测平台 .\tools\build\build.ps1 # 指定平台与配置构建 .\tools\build\build.ps1 -Platform x64 -Configuration Release # 仅构建核心工程runner settings加快本地迭代 .\tools\build\build-essentials.ps1 # 构建包含安装器在内的一切仅 Release .\tools\build\build-installer.ps1从源码进一步印证脚本的行为与参数语义tools/build/build.ps1 是面向「当前目录下工程」的轻量包装器它会 dot-source 同目录的build-common.ps1先调用Ensure-VsDevEnvironment定位并加载 VS 开发环境未传-Platform时通过Get-DefaultPlatform自动探测主机平台-Configuration默认值为Debug可用-Path指定含.sln/.csproj/.vcxproj的目标目录-RestoreOnly开关可只做包还原额外位置参数会被透传给 MSBuild例如/p:CIBuildtrue便于对接 CI 或私有构建属性对应 tools/build/build.ps1 的参数定义。tools/build/build-essentials.ps1 用于「快速迭代」场景先对PowerToys.slnx执行 NuGet 还原再只编译两个关键工程——原生 runner.\src\runner\runner.vcxproj与设置 UI.\src\settings-ui\Settings.UI\PowerToys.Settings.csproj并注入/p:SolutionDir...。也就是说只改 runner 或 Settings 相关代码时用这个脚本比全量构建快得多。它也支持-Platform arm64在 x64 机器上交叉产出 ARM64 版本对应 tools/build/build-essentials.ps1。完整的构建/CI 细节可进一步阅读 tools/build/BUILD-GUIDELINES.md其中涵盖了更底层的构建规范与辅助脚本说明。五、调试与新模块开发入口完成一次成功构建后推荐按下面两个官方文档深入调试专题Debugging 覆盖 Visual Studio 调试器配置、附加到子进程的方法PowerToys 是「runner 各模块子进程」架构很多模块需要 attach 到子进程才能断点命中以及常见构建错误的排查。新增一个 PowerToyCreating a New PowerToy 是一份端到端指南涵盖模块架构、设置项接入、安装器打包与测试。如果你想为Command Palette命令面板编写扩展原文档指向其独立扩展性文档仓库文档中以 aka.ms 短链给出介绍如何创建、打包并分发与 Command Palette 集成的自定义扩展。结合仓库可以快速定位命令行相关源码位于 src/modules/cmdpal其中ExtensionTemplate/TemplateCmdPalExtension/.vsconfig还自带一份扩展工程模板的 VS 组件清单可当作最小扩展样例来对照阅读。六、开发规范、代码风格与测试要求原文档在「Development Guidelines」和「Rules」两节给出了硬性约定归纳如下编码指南与最佳实践Coding Guidelines代码格式与风格约定Coding Style日志与遥测Logging and Telemetry多语言本地化LocalizationUI 测试编写UI Testing用 VS Code 开发Developing with VS CodeRules 一节原文给出的核心规则是Follow the pattern of what you already see in the code.沿用仓库既有代码模式——PowerToys 仓库同时含 C/WinRT、C#/WinUI 等多套技术栈紧跟既有实现是最重要的兼容性保障遵守 编码风格尽量把新功能/组件封装进「接口定义清晰」的库扩展既有代码时把新功能封装成类或把旧功能重构成类凡是新增/修改类与方法都要补充或更新单元测试。该规则与仓库实际的测试布局吻合例如src/common/UnitTests-CommonUtils、src/modules/cmdpal下的各类单测工程以及src/settings-ui/Settings.UI.UnitTests等说明测试是代码合入的强约束而非可选建议。七、GitHub 协作工作流与 PR 提交规范原文档定义了社区贡献者需要遵守的协作流程直接引用如下要点开工前确保存在一个追踪该修复/特性的 issue若你具备权限为 issue 添加In progress标签并补充Cost-Small/Medium/Large工作量评估及合适的标签社区贡献者无权限打标签时只需在 issue 下评论说明已开始工作并尽量给出交付时间预估若工作量较大Medium/Large用 Markdown 任务清单列出每个子项完成后勾选更新开 PR 前必须确保本地构建成功且功能测试通过。文档特别强调这对 AI 辅助vibe coding贡献尤其重要——必须验证 AI 生成的代码确实能工作仅用于讨论的探索性 PR 或 draft PR 除外开 PR 时遵循 PR 模板需要团队评审时即使工作尚未 100% 完成把 PR 标记为Ready For Review评审可能要经过多轮往返最终目标是得到可合并、可测试、符合规范的代码PR 批准后由 PR 作者负责合并社区贡献者的 PR 可由批准的 reviewer 代为合并合并方式优先使用Squash and merge若提交在逻辑上相互独立而不宜 squash则使用Rebase and merge可在 PR 描述中使用 GitHub 的 closing keywords如Fixes #123让 PR 合入时自动关闭关联 issue。仓库还维护了便于协作的辅助资源Issue/PR 命令自动化机器人指令与 aka.ms 短链接清单。八、核心架构从文档到代码的导航原文档为开发者提供了按主题组织的架构文档索引转换为仓库根目录相对路径后如下Architecture OverviewPowerToys 整体架构与模块接口总览Runner and System TrayPowerToys Runner 主进程系统托盘宿主细节Settings设置系统文档Installer安装器工作原理Modules各模块文档入口。架构的关键在于「Runner 单进程常驻 按需加载各模块」的分发模型这可以在代码层得到印证主进程源码集中在 src/runner其中 src/runner/main.cpp 负责进程启动与模块调度src/runner/powertoy_module.cpp 定义了模块生命周期管理而 src/runner/tray_icon.cpp 实现系统托盘交互各模块实现统一的模块接口native 模块契约见 src/common/interop托管模块契约见 src/common/PowerToys.ModuleContracts其中IModuleService.cs定义了服务接口这也是「把新功能封装进接口清晰库」规则的落地基础。对独立模块逐一深入前建议先阅读 Modules 与各模块子文档如 FancyZones、PowerRename、PowerToys Run、Mouse Without Borders 等均有专属文档。公共组件Common ComponentsContext Menu HandlersPowerToys 如何实现并注册文件资源管理器右键菜单处理器Monaco Editor多个模块如何复用 Monaco 代码编辑器组件仓库中对应 src/Monaco 与src/common/FilePreviewCommon/MonacoHelper.cs的封装。九、工具与流程Tools Processes原文档在 Tools 板块汇总了辅助开发与质量保障的工具Tools 总览Bug Report Tool收集日志与系统信息的 bug 上报工具工程位于 tools/BugReportToolDebugging Tools专项调试工具Fuzzing Testing如何对 PowerToys 模块实施模糊测试仓库也内置了相关模糊测试基础设置可参见 src/Common.Dotnet.FuzzTest.props构建类工具直接使用 tools/build/ 下脚本含证书管理 cert-management.ps1、打包签名 cert-sign-package.ps1 等。Processes 板块则面向发布与治理环节Release ProcessPowerToys 版本发布如何准备与推送Update Process内置更新机制如何工作代码侧参考 src/common/updating 与 src/runner/UpdateUtils.cppGPO Implementation组策略对象实现细节对应 src/gpo 与src/common/GPOWrapper。十、构建安装器EXE MSI 两段式打包PowerToys 的安装器由两部分组成原文档明确说明EXEBootstrapper内嵌 MSI处理更复杂的安装逻辑——负责安装全部前置依赖并通过 MSI 安装 PowerToys还支持安装参数/开关MSI安装 PowerToys 本体二进制。编译前提安装器只能在Release模式下编译且步骤 1、2 必须在 MSI 编译前完成。官方给出的完整顺序是编译 PowerToys.slnx方法见上文第四节编译 BugReportTool 工具路径tools\BugReportTool\BugReportTool.sln→ 仓库相对路径 tools/BugReportTool/BugReportTool.sln编译 StylesReportTool 工具路径tools\StylesReportTool\StylesReportTool.sln→ 仓库相对路径 tools/StylesReportTool/StylesReportTool.sln编译安装器解决方案installer\PowerToysSetup.slnx→ 仓库相对路径 installer/PowerToysSetup.slnx。更详细的安装器构建与调试方法见 Installer。若想在本地跑完整打包流水线也可以直接调用 tools/build/build-installer.ps1从脚本注释可知它默认以x64 Release PerUser(true)构建并打包 CmdPal 与安装器处理签名通过 tools/build/cert-sign-package.ps1与 WiX 生成产物输出在installer/PowerToysSetupVNext/[Platform]/[Configuration]/User[Machine]Setup下在其它机器上安装前需用 tools/build/cert-management.ps1 导出签名证书并在目标机器上信任。若需在非本仓库机器运行完整安装流程可参考仓库内 test-winget-install-locally 指南。十一、给新贡献者的速查清单综合原文档全部章节收敛出一份可直接照做的上手清单确认系统满足前置条件Win10 1803、VS 2026/VS2022 17.4 且含 .vsconfig 所列组件、.NET 8 SDK、长路径已开启Fork 并 Clone 仓库运行 tools/build/setup-dev-environment.ps1或winget configure .config\configuration.winget完成环境与子模块初始化在 VS 中打开 PowerToys.slnx 选择Release/Debug构建或使用 tools/build/build.ps1/build-essentials.ps1运行x64\Release\PowerToys.exe验证主程序需要外壳扩展类模块时补做安装器构建与安装开发前阅读 调试文档 与 新模块开发指南并严格遵守 编码指南、编码风格 与「改代码必带测试」的规则提交 PR 前本地构建 测试通过标记 Ready For Review合入采用 Squash/ Rebase and merge涉及打包时按第八节顺序依次编译解决方案与安装器工程。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考