Note
dotnetup 为公共预览版。 在正式发布之前，其功能和行为可能会更改。
本文介绍常见问题 dotnetup 及其解决方法。
收集诊断信息
在解决问题之前，请收集以下信息：
dotnetup显示版本、体系结构、运行时标识符和已验证的安装：dotnetup --info显示跟踪的安装规范和安装，并验证磁盘上的文件：
dotnetup list将存储的环境配置与当前环境进行比较：
dotnetup env show使用详细的输出再次运行失败的命令。 例如：
dotnetup sdk install 10.0 --verbosity detailed
项目无法构建，或者应用在安装后不会启动
症状：在 Windows 上以 dotnetup 模式设置 everywhere 后，之前可生成的项目现在无法生成。 或者，依赖于框架的应用显示此错误：
You must install or update .NET to run this application.
原因： 在 everywhere 模式下，dotnetup 托管安装优先于程序文件中的计算机范围的安装。 仅存在于全局安装中的 SDK 和运行时不可用。
解决方案： 将计算机范围的 SDK 和运行时迁移到 dotnetup 托管的安装中：
dotnetup sdk install --migrate-from-system
dotnetup runtime install --migrate-from-system
或者，更改为 shell 或 none 访问模式。 有关详细信息，请参阅 Everywhere 模式注意事项。
dotnet 不使用由 dotnetup 管理的安装
症状：终端中的 dotnet 命令不使用 dotnetup 安装的 SDK。
原因： 在更改环境之前 dotnetup ，终端已打开，或者环境配置与存储的配置不匹配。
Solution:
打开新的终端。 更改 shell 配置文件或Windows环境变量不会影响已打开的终端。
运行
dotnetup env show。 如果报告出现偏移，请再次运行dotnetup env set以应用存储的配置。若要仅配置当前终端，请对
dotnetup env script的输出求值。 例如，在 Bash 或 zsh 中：eval "$(dotnetup env script)"在 PowerShell 中：
dotnetup env script --shell pwsh | Invoke-Expression
有关详细信息，请参阅 “管理 dotnetup 环境”。
安装路径已包含未跟踪的安装
症状： 安装命令失败，并出现此错误：
The install path '<path>' already contains a .NET installation that is not tracked by dotnetup. To avoid conflicts, use a different install path, remove the existing installation first, or use the --untracked option to install without tracking.
原因：dotnetup不会将已跟踪的文件安装到包含一个它未跟踪的 .NET 安装的文件夹中。此检查可防止dotnetup将其文件与另一个工具拥有的文件混合。
解决方案： 执行下列操作之一：
- 使用
--install-path选项选择其他文件夹。 - 从该文件夹中移除现有安装。
- 如果另一个工具拥有该文件夹，请使用
--untracked选项。dotnetup不列出、更新或删除未跟踪的文件。
有关详细信息，请参阅 管理自定义安装根。
dotnet 可执行文件正在被使用
症状：在Windows，安装命令显示类似于以下消息的警告：
Warning: Could not update dotnet executable at '<path>' - it is currently in use by another process. Close all running .NET applications and try again. The existing muxer will be retained. ...
原因： 正在运行的进程使用 dotnet 可执行文件，因此 dotnetup 无法替换它。 安装将使用现有的 dotnet 可执行文件继续进行。
新的运行时可能需要较新的 dotnet 可执行文件。
解决方案：关闭所有正在运行.NET应用、IDE 和生成服务器。 然后，再次运行 install 命令。 若要使命令失败，而不是继续发出警告，请使用 --require-muxer-update 该选项。
另一个 dotnetup 进程正在运行
症状： 某个命令显示此消息并等待：
Another dotnetup process is running. Waiting for it to finish...
原因：dotnetup 对共享安装状态的更改进行序列化。 另一个 dotnetup 命令正在更改相同的状态。
解决方案： 等待其他命令完成。 如果没有其他 dotnetup 进程运行，请查找已停止响应的 dotnetup 进程并结束这些进程。
自我更新不会替换可执行文件
症状：dotnetup self update 报告说未应用任何更新。
原因： 所选通道包含同一版本或较旧版本。
官方每日版本还带有 preview 标签，默认为预览频道。
解决方案： 若要保持每日构建版本，请运行 dotnetup self update --channel daily。
若要有意重新安装或降级到最新的预览版，请运行 dotnetup self update --channel preview --force。
自动更新失败
症状：dotnetup self update 因其可执行位置、权限、验证或其他活动命令而失败。
Solution:
- 从其实际安装目录运行独立可执行文件，而不是通过
dotnet宿主程序或可执行的符号链接运行。 - 检查你是否对安装目录具有写入访问权限。
- 如果另一个命令持有锁，请让它完成，然后重试。
- 如果验证失败，请不要绕过校验和或签名检查。 报告该故障。
- 如果该可执行文件无法启动，请使用下载脚本重新安装它。
对于无法识别命令的较旧版本，请使用下载脚本安装当前预览版。 有关验证和未签名下载策略的详细信息，请参阅 dotnetup 可执行文件。
清单文件已损坏
症状： 命令失败并出现此错误：
The dotnetup manifest at <path> is corrupt. Consider deleting it and re-running the install.
该消息还可以说明文件是在 dotnetup 外部修改的。
原因：dotnetup_manifest.json 文件无效。 另一个进程或手动编辑可能已更改文件。
解决方案： 从 dotnetup 数据目录中删除清单文件及其 .sha256 文件。 然后，重新安装所需的 SDK 和运行时。 由于清单不再跟踪现有安装根目录，因此可能还需要先删除该文件夹。 有关数据目录的位置，请参阅 “更新或删除 dotnetup”。
Note
请勿编辑清单文件（manifest）。 使用 dotnetup 命令更改跟踪状态。
配置文件已损坏
症状： 命令显示以下警告：
Warning: The dotnetup config file at <path> appears to be corrupted and could not be read: ...
原因：dotnetup.config.json 文件无效。
dotnetup 忽略该文件。
解决方案： 使用所需的访问模式运行 dotnetup env set ，或再次运行 dotnetup init 。 这些命令会写入新的配置。
shell 配置文件包含格式不正确的 dotnetup 块
症状： 一个 env 命令失败，出现类似于以下消息的错误：
The shell profile '<path>' contains a malformed dotnetup block: '<begin marker>' does not have a matching '<end marker>'. Remove or repair the block manually and try again.
原因：dotnetup 通过起始和结束注释，标记其添加到 shell 配置文件中的行。 其中一个注释缺失。
解决方案： 在文本编辑器中打开 shell 配置文件。 删除不完整的 dotnetup 块，或添加缺失的标记。 然后再次运行该命令。
已取消权限提升
症状：在 Windows 上，开启或关闭everywhere模式的命令会显示以下消息：
Elevation was cancelled. The system PATH was not modified.
原因：对系统的 PATH 更改需要提升权限。 用户帐户控制（UAC）提示已取消。
解决方案： 再次运行该命令并批准 UAC 提示符。 或者，选择 shell 或 none 访问模式，无需提升权限。
发布清单已过期
症状： 安装或更新在发布清单验证期间失败，并出现 ExpiredNow 失败代码。
原因： 当前系统时间在清单过期时间或之后。 清单可能已过期，或者系统时钟可能不正确。 有效的签名不能使过期的清单可以接受。
Solution:
- 检查系统的日期和时间。 如有必要，请更正时钟设置。
- 请重试该命令。 如果代理服务器提供缓存的发布元数据，请让管理员检查它是否提供了过期的清单。
- 如果时钟正确且故障仍然存在，请连同该命令的详细输出一起报告该问题。
请勿编辑清单或更改时钟以绕过过期检查。 有关详细信息，请参阅 清单过期。
安装被 IT 策略阻止
症状： 安装每日或预发行版本失败，并显示一条消息，指出 IT 策略要求下载内容经过代码签名。
原因： 管理员阻止了计算机上的未签名下载。
解决方案： 安装已发布的版本，或要求管理员清除策略。 有关详细信息，请参阅 dotnetup 如何验证下载。
报告问题
如果本文无法解决问题，请搜索 现有的 dotnetup 问题。
如果未找到匹配项，请使用 dotnetup 问题模板在 dotnet/sdk 存储库中打开一个新问题。 包含 dotnetup --info 的输出以及带有 --verbosity detailed 的失败命令输出。
有关问题和建议，请使用 dotnetup 讨论。
