如何从源码构建并调试 Windows Terminal：环境准备与 CascadiaPackage 启动步骤

如何从源码构建并调试 Windows Terminal：环境准备与 CascadiaPackage 启动步骤

【免费下载链接】terminalThe new Windows Terminal and the original Windows console host, all in the same place!项目地址: https://gitcode.com/GitHub_Trending/term/terminal

如果你的目标是在 Visual Studio 里把本仓库（Windows Terminal、conhost 及其共享组件的源码仓库）构建出来，并让本地构建的 Windows Terminal 跑在调试器下，那么需要走通一条固定的路径：准备 Windows 10 2004（build 19041）及以上的机器、用 VS 2026 打开OpenConsole.slnx完成构建、再通过打包项目CascadiaPackage部署并调试。仓库的 README.md 与 doc/building.md 给出了完整的构建与部署命令，doc/Debugging.md 说明了打包应用断点不命中时的修正方法。

环境准备：先核对这组硬性前提

README.md 列出的构建前提是：

• Windows 10 2004（build >= 10.0.19041.0）或更高版本；
• 在 Windows 设置中启用开发者模式（Developer Mode），本地安装和运行 Windows Terminal 需要它；
• PowerShell 7 或更高版本；
• Windows 11 (10.0.26100) SDK，版本 10.0.26100.8249 或更高；
• VS 2026（version 18.6）或更高；
• 通过 VS Installer 安装两个工作负载：Desktop Development with C++ 和 WinUI application development（README 提示：打开解决方案时 VS 也会提示自动安装缺失组件）；
• .NET Framework 4.7.2 Targeting Pack——仅构建测试项目时需要。

如果不想逐项手工安装，仓库自带 Winget 配置文件。.config/configuration.winget 是默认配置，会依次启用开发者模式、安装 PowerShell 7、安装 Visual Studio 2026 Community，并按仓库根目录的.vsconfig安装所需的 VS 组件；.config目录下另有 Enterprise 与 Professional 两个版本的配置变体。在仓库根目录执行：

winget configure .config\configuration.winget

该配置文件中多个资源声明了securityContext: elevated，即安装和启用开发者模式时需要提权，执行前留意 UAC 弹窗。

获取源码并首次构建

仓库的部分依赖通过 git submodule 提供，doc/building.md 要求构建前先执行：

git submodule update --init --recursive

构建有两条等价路径。PowerShell 主路径（README.md、doc/building.md）：

Import-Module .\tools\OpenConsole.psm1 Set-MsBuildDevEnvironment Invoke-OpenConsoleBuild

Cmd 替代路径：

.\tools\razzle.cmd bcz

razzle.cmd负责把 msbuild 和 tools 目录加入 PATH，并把默认构建配置设为Debug（bcz dbg/bcz rel可手动指定配置，见 tools/README.md）。构建完成的判断：命令无错误返回；若后续走命令行部署，src\cascadia\CascadiaPackage\AppPackages\下会出现CascadiaPackage_0.0.1.0_x64_Debug_Test之类的包输出目录。

可选：用 VS 打开OpenConsole.slnx时，文档建议顺手配置 clang-format——先运行Get-Format（同一 PowerShell 会话里）下载所需的 clang-format.exe，再到 Tools > Options > Text Editor > C++ > Formatting 勾选 "Use custom clang-format.exe file" 并指向/packages/clang-format.win-x86.10.0.0/tools/clang-format.exe。

配置并启动 CascadiaPackage 调试（主路径）

调试 Windows Terminal 的入口不是可执行文件，而是打包项目CascadiaPackage。

1. 在解决方案平台选择器中选x64或x86。不能选 "Any CPU"——Terminal 是 C++ 应用，不支持 Any CPU 构建。
2. 在 Solution Explorer 中右键CascadiaPackage→ Properties，进入 Debug 菜单，把 "Application process" 和 "Background task process" 都改成 "Native Only"。doc/Debugging.md 说明：不做的后果是默认断点根本不会命中（默认是 Mixed (Managed and Native)）。
3. 按 F5 构建并调试。

从 VS 构建打包项目时，会先生成 loose layout 并直接注册 loose manifest，跳过 msix 这一步，比命令行内环快得多（doc/building.md）。

两条与"启动"直接相关的边界，先说清楚以免走弯路：

• 直接运行WindowsTerminal.exe是启动不了 Terminal 的，README.md 明确提示只能按上面的打包流程启动；
• README.md 的 FAQ 指出：如果构建后启动的东西"看起来就是老控制台"，原因通常是构建/部署了错误的项目。确认你构建和部署的是CascadiaPackage。OpenConsole.exe只是本地构建的conhost.exe，它长成老控制台的样子是正常的——它由 Windows Terminal 通过 ConPTY 用来连接命令行程序。

命令行构建与部署 msix 包（可选分支）

如果不想依赖 VS 的 F5，doc/building.md 给出了一条命令行路径。前提是已经用tools\razzle.cmd初始化过当前窗口（%msbuild%、%OPENCON%、%_LAST_BUILD_CONF%、%ARCH%都由它提供），且平台为 x64：

"%msbuild%" "%OPENCON%\OpenConsole.slnx" /p:Configuration=%_LAST_BUILD_CONF% /p:Platform=%ARCH% /p:AppxSymbolPackageEnabled=false /t:Terminal\CascadiaPackage /m

这一步耗时较长，且只生成 msix、不安装。生成后用 PowerShell 部署，命令原样来自 doc/building.md：

Import-Module .\tools\OpenConsole.psm1 Set-MsBuildDevEnvironment Set-Location -Path src\cascadia\CascadiaPackage\AppPackages\CascadiaPackage_0.0.1.0_x64_Debug_Test if ((Get-AppxPackage -Name 'WindowsTerminalDev*') -ne $null) { Remove-AppxPackage 'WindowsTerminalDev_0.0.1.0_x64__8wekyb3d8bbwe' } New-Item ..\loose -Type Directory -Force makeappx unpack /v /o /p .\CascadiaPackage_0.0.1.0_x64_Debug.msix /d ..\loose\ Add-AppxPackage -Path ..\loose\AppxManifest.xml -Register -ForceUpdateFromAnyVersion -ForceApplicationShutdown

这条链路的副作用需要清楚：Remove-AppxPackage会卸载机器上已注册的本地开发包（WindowsTerminalDev*）；New-Item ..\loose在仓库的src\cascadia\CascadiaPackage\下新建loose目录；makeappx unpack把 msix 解包进该目录；最后Add-AppxPackage从解包出的AppxManifest.xml注册本机构建。Set-MsBuildDevEnvironment的作用是定位 makeappx 的路径。WindowsTerminalDev_0.0.1.0_x64__8wekyb3d8bbwe是文档中固定的开发包 family 名，对应仓库默认的版本号 0.0.1.0 与 x64 Debug 构建，路径中的x64要求你构建的就是 x64 平台。

文档还记录了另一条bx+DeployAppRecipe.exe的部署方式，但其中路径写死为 VS 2022 Preview 的安装位置，且文档自述该方式无法利用 VS 的 FastUpToDate 检查、整体更慢，本文不将其作为主路径。

验证结果与排查部署失败

验证主路径是否走通：F5 后本地 Terminal 启动，且窗口是新 Terminal 的形态而不是老控制台。若启动出来的是"老控制台样子"，按 FAQ 核对是否部署了CascadiaPackage项目。

遇到DEP0700: Registration of the app failed. [0x80073CF6] error 0x80070020时：doc/building.md 记录的原因是OpenConsoleProxy.dll被其他终端包占用、注册被锁住。排查方式是把 VS 的部署替换为等价的 PowerShell 命令，该命令会给出 ActivityId：

Add-AppxPackage -register "src\cascadia\CascadiaPackage\bin\x64\Debug\AppX\AppxManifest.xml"

上面的路径是仓库内的实际输出位置，文档原文使用作者本机路径，替换成你构建后的真实路径。随后按命令提示查询日志：

Get-AppPackageLog -ActivityID <上一步输出中的 ActivityId>

文档中的实际案例显示，日志关键行是访问C:\ProgramData\Microsoft\Windows\AppRepository\Packages\WindowsTerminalDev_0.0.1.0_x64__8wekyb3d8bbwe时被拒绝（access denied），定位到是PackagedCom中的OpenConsoleProxy.dll被残留的终端进程锁住；结束这些挂起的终端进程后即可重新部署。

另外，构建脚本导出函数中的Invoke-OpenConsoleTests默认运行单元测试（Cmd 下对应runut.cmd），doc/building.md 将其列为环境自检的一部分。

限制

• 调试与部署均要求平台为x64或x86，不支持 Any CPU。
• 命令行部署路径按 x64 Debug 包（0.0.1.0版本）书写，换平台或 Release 配置时需要相应替换包目录与 family 名。
• 仓库的三套配置类型是 Debug、Release、AuditMode，其中 AuditMode 是启用 CppCoreCheck 额外静态分析的实验模式（doc/building.md）。

【免费下载链接】terminalThe new Windows Terminal and the original Windows console host, all in the same place!项目地址: https://gitcode.com/GitHub_Trending/term/terminal