在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

microsoft/PowerToys

菜单

从源代码构建

相关源文件

本文档提供了设置开发环境和从源代码构建 PowerToys 的全面说明。它涵盖了构建系统架构、依赖项管理以及 C++ 和 C# 组件的完整构建过程。

有关创建新 PowerToys 模块的信息，请参阅 创建新的 PowerToy。有关开发调试工具的详细信息，请参阅 调试工具。

先决条件

构建 PowerToys 需要特定的开发工具和 Windows SDK 版本，以确保所有模块的兼容性。

所需工具

  • Visual Studio 2022（17.0 及更高版本），包含以下工作负载：
    • 使用 C++ 进行桌面开发
    • .NET 桌面开发
    • Windows 应用程序开发
  • Windows SDK 10.0.22621.0（最低版本 10.0.19041.0）
  • Git，用于源代码管理
  • PowerShell 7（建议用于构建脚本）

系统要求

  • Windows 10 版本 19041 或更高版本（建议使用 Windows 11）
  • 架构：x64 或 ARM64
  • 内存：最低 8GB RAM（建议 16GB）
  • 存储：10GB 可用空间，用于源代码和构建输出

来源：Cpp.Build.props99-102 src/settings-ui/Settings.UI/PowerToys.Settings.csproj1-21

构建系统架构

PowerToys 使用混合构建系统，结合 MSBuild 来处理 C++ 和 C# 项目，并通过 NuGet 进行集中的依赖项管理。

项目结构概览

MSBuild 配置系统

来源：Directory.Packages.props1-110 Cpp.Build.props1-126 src/settings-ui/Settings.UI/PowerToys.Settings.csproj1-149

依赖管理

PowerToys 支持集中式包版本管理，以确保整个解决方案中所有项目的一致性。

集中式程序包管理

构建系统在 Directory.Packages.props 中使用集中式 NuGet 包版本控制

包类别

类别目的关键包
Windows 应用 SDKWinUI3、现代 Windows APIMicrosoft.WindowsAppSDK
WinRT 互操作C++/WinRT 投影Microsoft.Windows.CppWinRT, Microsoft.Windows.CsWinRT
UI 框架WinUI3 社区控件CommunityToolkit.WinUI.*
系统集成Windows SDK、WebView2Microsoft.Windows.SDK.BuildTools, Microsoft.Web.WebView2
开发工具代码分析、测试Microsoft.CodeAnalysis.NetAnalyzers, MSTest

来源：Directory.Packages.props5-104 src/modules/powerrename/PowerRenameUILib/packages.config1-10

构建配置

PowerToys 支持多种构建配置，以适应不同的部署场景和目标体系结构。

平台和配置矩阵

C++ 特定设置

C++ 构建配置位于 Cpp.Build.props 中，定义了项目范围的编译器和链接器设置。

设置Debug 值Release 值目的
优化已禁用MaxSpeed性能优化
运行时库MultiThreadedDebugMultiThreaded静态运行时链接
控制流保护GuardGuard安全功能
语言标准stdcpplateststdcpplatest现代 C++ 功能
警告级别Level4Level4严格警告报告

来源：Cpp.Build.props71-95 src/modules/powerrename/PowerRenameUILib/PowerRenameUI.vcxproj33-47

构建流程

构建过程涉及多个阶段，从环境设置到最终输出生成。

构建管道

命令行构建

适用于自动化构建或 CI/CD 场景

构建输出结构

PowerToys/
├── x64/
│   ├── Debug/
│   │   ├── PowerToys.exe                 # Main runner executable
│   │   ├── WinUI3Apps/
│   │   │   ├── PowerToys.Settings.exe   # Settings application
│   │   │   ├── PowerToys.PowerRename.exe # PowerRename UI
│   │   │   └── PowerToys.MeasureToolCore.dll
│   │   └── Tools/
│   │       └── PowerToys.BugReportTool.exe
│   └── Release/ # Same structure as Debug
└── ARM64/       # Same structure as x64

来源：src/runner/UpdateUtils.cpp81-92 tools/BugReportTool/BugReportTool/BugReportTool.vcxproj18-19

开发环境设置

设置开发环境需要仔细关注工具版本和配置。

分步设置

  1. 克隆仓库

  2. 安装先决条件

    • 安装 Visual Studio 2022 及所需工作负载
    • 确保已安装 Windows SDK 10.0.22621.0
    • 安装 Git 和 PowerShell 7

  3. 配置 Visual Studio

    • 在 Visual Studio 中打开 PowerToys.sln
    • 将启动项目设置为 runner 以进行调试
    • 配置构建平台（开发建议使用 x64）

  4. 验证构建环境

代码分析配置

PowerToys 包含在 CppRuleSet.ruleset 中定义的全面代码分析规则

版本管理

构建系统通过 PowerShell 脚本包含自动版本管理

  • UpdateVersions.ps1：更新所有项目中的 WindowsAppSDK 版本
  • 集中版本控制：Directory.Packages.props 维护一致性
  • 程序包源管理：nuget.config 配置

来源：CppRuleSet.ruleset1-323 .pipelines/UpdateVersions.ps1115-165 Cpp.Build.props25-29

常见问题排查

程序包还原问题

问题：NuGet 包还原失败 解决方案

  1. 清除 NuGet 缓存：dotnet nuget locals all --clear
  2. 验证 nuget.config 中的程序包源
  3. 检查 Directory.Packages.props 以查看版本冲突

构建配置不匹配

问题：混合平台或配置错误 解决方案

  1. 确保平台选择一致（x64 vs ARM64）
  2. 清理解决方案：Build > Clean Solution
  3. 验证项目引用是否与目标平台匹配

Windows SDK 版本问题

问题：找不到 SDK 版本错误 解决方案

  1. 通过 Visual Studio Installer 安装 Windows SDK 10.0.22621.0
  2. 如有需要，请更新项目文件中的 WindowsTargetPlatformVersion
  3. 在 Windows Kits 目录中验证 SDK 安装

WinUI3/WindowsAppSDK 冲突

问题：WindowsAppSDK 版本不匹配 解决方案

  1. 运行 UpdateVersions.ps1 以同步版本
  2. 检查是否有冲突的程序包引用
  3. 确保 WinUI3 项目中 WindowsAppSDKSelfContained=true

来源：.pipelines/UpdateVersions.ps1129-165 src/settings-ui/Settings.UI/PowerToys.Settings.csproj16-21