企业官网建设流程全解析

PowerToys 如何搭建 Visual Studio 开发环境并完成首次源码构建？

【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys

如果你已经拿到 PowerToys 的源码仓库，想在自己的 Windows 机器上打开解决方案、跑通一次完整构建，并且能定位构建失败的位置，这篇文章就是给你准备的。按下面的顺序操作：核对系统前提 → 安装 Visual Studio 及所需工作负载 → 克隆仓库并执行环境初始化脚本 → 在 Visual Studio 或命令行中构建 → 验证x64\Release\PowerToys.exe产物。整个过程依据仓库内 开发者文档 和 构建脚本指南。

核对系统与工具链前提

PowerToys 文档列出的前置条件如下，构建前先逐项确认：

• Windows 10 April 2018 Update（1803）或更高版本；
• Visual Studio 2026（推荐）或 Visual Studio 2022 17.4+，并安装以下工作负载/组件：
  • Desktop development with C++
  • WinUI application development
  • .NET desktop development
  • Windows 11 SDK (10.0.22621.0)
  • Windows 11 SDK (10.0.26100.3916)
• .NET 8 SDK；
• Windows 长路径支持已开启（开发者文档要求，开启方法见其引用的 Windows 文档链接）。

这些前提可以直接对照 doc/devdocs/readme.md 的 "Prerequisites" 一节核对。

安装 Visual Studio 与所需工作负载

文档提供两条路径，任选其一：

路径 A：用仓库内的 WinGet 配置文件自动安装（文档推荐用于全新机器）

仓库根目录的.config目录带有 Visual Studio 的 WinGet 配置文件，configuration.winget会自动安装带所需工作负载的 Visual Studio。选择与你 VS 版本匹配的文件，例如configuration.vsProfessional.winget或configuration.vsEnterprise.winget：

winget configure .config\configuration.winget

路径 B：已有 Visual Studio，手动补齐组件

用 Visual Studio Installer 导入仓库根目录的 .vsconfig 文件，安装全部所需工作负载。或者打开 PowerToys.slnx，如果解决方案资源管理器面板出现install extra components对话框，点击install即可补齐缺失组件。

克隆仓库并执行环境初始化脚本

先在 GitHub 上 Fork 仓库并克隆到本地。克隆完成后，在仓库根目录（PowerShell）运行文档推荐的自动化环境脚本：

.\tools\build\setup-dev-environment.ps1

setup-dev-environment.ps1 会依次执行四步：

1. 开启 Windows 长路径支持（需要管理员权限）；
2. 开启 Windows Developer Mode（需要管理员权限）；
3. 从.vsconfig安装所需 Visual Studio 组件（脚本会先检测 VS 安装路径，交互提示是否立即调用 VS Installer 安装）；
4. 初始化 git 子模块（等价于git submodule update --init --recursive）。

需要注意的副作用与前提：

• 脚本以管理员运行时直接写入注册表开启长路径和 Developer Mode；非管理员运行时对应步骤会跳过并给出警告，你需要手动以管理员身份再跑或手动开启这两项。
• 第 3 步会启动 Visual Studio Installer，安装前脚本提示先关闭正在运行的 Visual Studio。
• 脚本是幂等的，可重复运行；用-Help查看全部选项，-SkipLongPaths、-SkipDevMode、-SkipVSComponents、-SkipSubmodules可分别跳过对应步骤，-VSInstallPath可手动指定 VS 安装路径。

如果不想用脚本，手动路径是：打开PowerToys.slnx处理组件安装提示，然后在仓库根目录执行git submodule update --init --recursive（这是一次性步骤，初始化前大部分模块无法编译）。

在 Visual Studio 中完成首次构建

这是文档给出的主路径：

1. 用 Visual Studio 打开 PowerToys.slnx；
2. 在Solutions Configuration下拉菜单中选择Release或Debug；
3. 从Build菜单选择Build Solution，或按Ctrl+Shift+B；
4. 构建完成后，PowerToys 二进制输出在仓库下的x64\Release\目录。

构建完成后可直接运行x64\Release\PowerToys.exe验证，无需安装 PowerToys。但文档明确说明：PowerRename、ImageResizer、文件资源管理器扩展等模块在未构建并安装安装器的情况下不可用——如果你的目标是验证这些模块，需要继续走安装器构建流程。

命令行构建（可选替代路径）

文档同时提供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

• build.ps1 的-Platform缺省时自动检测宿主平台，-Configuration缺省为Debug；额外参数（如/p:CIBuild=true）会原样转发给 MSBuild，-RestoreOnly只执行 NuGet 还原。
• build-essentials.ps1 先对整个PowerToys.slnx还原 NuGet 包，再只构建runner.vcxproj和PowerToys.Settings.csproj两个核心项目。
• build-installer.ps1是完整的本地打包管线（还原、构建、签名 MSIX、WiX v5 MSI/bootstrapper），并会清理installer/下部分输出；完整本地打包才用它。

Debugging 文档 还给出了不用脚本的裸 MSBuild 命令（在 "Developer Command Prompt for VS" 中执行，文档示例为 ARM64 平台）：

msbuild -restore -p:RestorePackagesConfig=true -p:Platform=ARM64 -m PowerToys.slnx /tl /p:NuGetInteractive="true"

文档给出的参考耗时：全量构建约 13–14 分钟，具体时间取决于机器性能。

构建失败时查看哪里

仓库构建脚本在失败时会把日志写到被构建解决方案/项目旁边（见 BUILD-GUIDELINES.md）：

• build.<configuration>.<platform>.all.log— 完整日志
• build.<configuration>.<platform>.errors.log— 仅错误
• build.<configuration>.<platform>.warnings.log— 仅警告
• build.<configuration>.<platform>.trace.binlog— 可用 MSBuild Structured Log Viewer 打开

如果构建报缺图片文件（.png、.ico等资源）之类的错误，文档判断这是构建状态损坏，处理顺序为：

1. 在 Visual Studio 中 Build > Clean Solution，或命令行执行msbuild PowerToys.slnx /t:Clean /p:Platform=x64 /p:Configuration=Debug；
2. 删除仓库根目录下的x64/、ARM64/、Debug/、Release/、packages/输出目录（这是删除构建产物，不影响源码）；
3. 重新构建。

仓库也提供了对应的清理脚本，它会执行 MSBuild Clean 并删除上述目录，加-SkipMSBuildClean可只删目录：

.\tools\build\clean-artifacts.ps1

清理后用如下命令重新构建：

msbuild -restore -p:RestorePackagesConfig=true -p:Platform=x64 -m PowerToys.slnx

另一个常见坑：构建脚本会先尝试 DevShell（Microsoft.VisualStudio.DevShell.dll/Enter-VsDevShell）再回退VsDevCmd.bat来初始化 VS 环境；如果脚本找不到 VS，改用 "Developer PowerShell for VS" 启动终端，或确认Program Files (x86)\Microsoft Visual Studio\Installer下存在vswhere.exe。

构建之后的限制与下一步

• 直接运行x64\Release\PowerToys.exe时，依赖安装器注册的模块（PowerRename、ImageResizer、文件资源管理器扩展等）不可用；要覆盖这些模块，需构建安装器，且安装器只能在Release模式下编译（build-installer.ps1，仅 Release）。
• 要在 Visual Studio 中调试，文档建议把runner项目设为启动项目；调试 FancyZones、Shortcut Guide 等涉及提权窗口的场景时，建议以管理员权限运行 Visual Studio。详见 Debugging。
• 后续要写自己的 PowerToy 模块，继续阅读 Creating a New PowerToy；编码规范见 Coding Guidelines。

【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys