PowerShell 源码构建失败时如何用 Start-PSBuild -Clean、-Restore 与 -ResGen 恢复【免费下载链接】PowerShellPowerShell for every system!项目地址: https://gitcode.com/GitHub_Trending/po/PowerShell从源码构建 PowerShell 时常见的失败场景是环境本身没问题但本地构建状态已经损坏——依赖没更新、资源文件改动后没有重新生成绑定、或者残留了旧的构建产物。docs/FAQ.md 在 “Why did my build fail?” 一节给出的通用结论是解决大多数构建问题的最简单方式是运行Start-PSBuild -Clean而依赖变化和资源变化各有对应的恢复参数-Restore和-ResGen。本文按“通用恢复 → 按失败原因选择参数 → 验证”的顺序给出可直接执行的恢复路径。准备条件构建环境要满足什么以下前提来自 docs/building/linux.md 和 build.psm1 中的构建模块说明Windows/macOS 用户可参考 docs/building/windows-core.md 与 docs/building/macos.md已递归克隆 PowerShell 仓库并cd到仓库根目录构建文档明确假设这一点。有一份自托管的 PowerShell 用于执行构建脚本。Linux 上可用仓库自带脚本安装./tools/install-powershell.sh pwsh构建入口是仓库根目录的build.psm1模块Start-PSBuild是其中的构建函数Import-Module ./build.psm1Start-PSBuild启动前会做两项 precheckgit和dotnet必须在 PATH 中缺失时会分别提示 “Build dependency git not found in PATH” 和 “Build dependency dotnet not found in PATH. Run Start-PSBootstrap.” 并直接中止。如果检测到的 dotnet 版本不是所需版本脚本会打印警告而不是构建警告中给出的官方修复步骤是删除已安装版本Windows 在$env:LOCALAPPDATA\Microsoft\dotnetmacOS/Linux 在$env:HOME/.dotnet然后运行Start-PSBootstrap或Install-Dotnet最后运行Start-PSBuild -Clean。项目默认引用需要认证的私有 Azure Artifacts 源。公开构建请加上-UseNuGetOrg它会切换构建到公开的 NuGet.org 源见 docs/building/linux.md 的说明。工具链不完整时例如新机器Linux 上可先执行Start-PSBootstrap -Scenario Both它会通过包管理器安装构建依赖并下载 .NET SDK 到~/.dotnet。注意 docs/FAQ.md 特别指出如果你之前用MSI、exe、apt-get或pkg装过 .NET CLI必须先手动卸载其他版本Start-PSBootstrap才能正确接管。通用恢复路径Start-PSBuild -Clean当构建失败但找不到具体原因时先走这条最短路径Start-PSBuild -Clean -UseNuGetOrg-Clean的作用在 build.psm1 的文档和实际实现build.psm1中都写明了构建前执行git clean -fdX删除未跟踪与被忽略的文件排除项为.vs/PowerShell/v16/Server/sqlite3、src/Modules/nuget.config和根目录nuget.config后两者是发布构建所需的。执行前需要知道它的副作用仓库内被 gitignore 的生成物旧的 bin/obj 输出、上一次生成的绑定文件等会被删除这是有意为之目的是让下一次构建从干净状态开始命令只在仓库根目录下执行不会动仓库外的文件。一个值得注意的联动机制-Clean删掉生成目录后Start-PSBuild内部的启发式判断会自动补跑资源与类型目录生成。build.psm1 中只要src/Microsoft.PowerShell.ConsoleHost/gen目录不存在就会运行Start-ResGen同理 build.psm1 中src/TypeCatalogGen/powershell_runtime.inc不存在时会自动运行Start-TypeGen。所以-Clean之后的构建通常会同时完成资源重新生成这也是 FAQ 推荐它作为“万能恢复”的原因。依赖变化时用 Start-PSBuild -Restoredocs/FAQ.md 的 “Dependency changed” 一节说明如果任何project.json中的包依赖发生了变化必须手动执行dotnet restore来更新本地依赖图Start-PSBuild -Restore会自动替你做这件事。从 build.psm1 的参数文档看-Restore的语义是强制NuGet 包恢复——即使包已经存在也会重新恢复。构建内部由Restore-PSPackage对根目录以及src/TypeCatalogGen、src/ResGen、src/Modules、tools/wix等项目目录逐个执行dotnet restore。依赖没变、包缓存完好时不需要加这个参数怀疑依赖图过期例如拉取了改动依赖的分支后构建失败时加上它重跑构建Start-PSBuild -Restore -UseNuGetOrg资源或字符串编译错误时用 Start-PSBuild -ResGendocs/FAQ.md 的 “Resource changed” 一节指出Start-PSBuild只在第一次运行时自动调用Start-ResGen后续构建如果需要必须显式使用Start-PSBuild -ResGen“当你看到与 strings 相关的编译错误时”就应该试它。背后的机制在 docs/dev-process/resx-files.md资源是存放在src\project\resources目录下的.resx文件错误消息等字符串都来自这里而dotnet cli不支持从 resx 生成 C# 绑定所以项目用自有的Start-ResGen工具src/ResGen 下的 .NET 工具为所有 resx 文件生成强类型资源类。Start-PSBuild中的判断逻辑是-ResGen被指定或src/Microsoft.PowerShell.ConsoleHost/gen目录不存在时运行Start-ResGen见 build.psm1 与 build.psm1。因此针对资源问题的恢复命令是Start-PSBuild -ResGen -UseNuGetOrg也可以单独调用Start-ResGen先只做重新生成确认没有报错后再完整构建。另外 docs/dev-process/resx-files.md 提醒编辑.resx文件要用纯文本编辑器不要用 Visual Studio 编辑VS 会尝试生成.cs文件并引发一堆难以理解的错误——如果你改过资源文件后构建失败这一点本身就可能是原因。同类地FAQ 还提到-TypeGen参数用于重新生成类型目录文件CorePsTypeCatalog.cs适用条件是类型目录文件与当前代码不一致时用法与-ResGen相同。其他两类文档明确给出的失败模式文件被占用导致编译失败。-StopDevPowerShell参数的文档说明build.psm1构建前停止正在运行的 dev pwsh 进程以避免 “file in use” 编译错误。它会结束那些加载了本次构建输出目录中模块的pwsh进程副作用就是这些正在运行的会话会被终止——如果你没有开着这类调试会话可以不加如果构建报文件占用类错误加上它Start-PSBuild -StopDevPowerShell -UseNuGetOrgdotnet 缺失或版本不对。前面 precheck 一节已覆盖缺dotnet时运行Start-PSBootstrap版本不符时按脚本警告里的三步走删旧版本 →Start-PSBootstrap/Install-Dotnet→Start-PSBuild -Clean。注意 docs/FAQ.md 对Start-PSBootstrap的强调必须先手动卸载其他安装方式的 CLI 版本它才能正确安装。验证构建是否恢复构建成功与否有明确的判断依据均来自 docs/building/linux.mdStart-PSBuild完成时会输出可执行文件的位置日志中的 “PowerShell output: …” 行即构建产物路径以 Linux Debug 默认配置为例文档给出的产物路径是./src/powershell-unix/bin/Debug/net11.0/linux-x64/publish/pwsh文档示例路径实际路径以你构建时的 Runtime/Configuration 参数为准运行该可执行文件如果能正常进入你自己构建出来的 PowerShell 会话说明构建已恢复。如果构建成功后还想跑测试验证docs/building/linux.md 给出的后续命令是Start-PSPester -UseNuGetOrgPester 测试与Start-PSxUnitxUnit 测试。适用边界docs/building/linux.md 的说明基于 Ubuntu 24.04 LTSCI 使用 ubuntu-latest构建模块对其他发行版只是 best-effort 支持发行版相关的怪问题可先考虑换到受支持的发行版再复现。私有源认证问题不属于本文的-Clean/-Restore/-ResGen能解决的范畴如果失败发生在 restore 阶段的认证上需要先解决 Azure Artifacts 的凭据或改用-UseNuGetOrg切换到公开源。-Clean会删除 gitignore 的生成文件执行前确认没有需要保留的本地未跟踪产物三个恢复参数本身不改变构建配置恢复后仍按你原有的 Runtime/Configuration 参数构建。参考资料docs/FAQ.md、docs/dev-process/resx-files.md、docs/building/linux.md、docs/building/windows-core.md、build.psm1。【免费下载链接】PowerShellPowerShell for every system!项目地址: https://gitcode.com/GitHub_Trending/po/PowerShell创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考