NuGet包默认安装路径如何修改？

Question

如何修改NuGet包的默认安装路径？默认情况下，NuGet会将包安装到用户目录下的 `%USERPROFILE%\.nuget\packages` 中，但在团队协作或多项目环境中，可能希望统一包存储位置以节省磁盘空间或便于版本控制。虽然 NuGet 本身不直接支持通过配置文件更改全局包路径，但可通过设置环境变量 `NUGET_PACKAGES` 或在 `nuget.config` 文件中配置 `` 来实现。然而，部分场景下该配置可能未生效，尤其是在使用 PackageReference 格式或 .NET SDK 项目时。常见问题包括路径权限不足、多层级配置优先级混乱以及 CI/CD 环境中路径未同步等。如何正确设置并确保自定义路径被所有项目和工具链一致识别？

Answer 1

一、NuGet 包默认安装路径的机制与挑战

NuGet 是 .NET 生态中广泛使用的包管理器，其默认行为是将所有下载的包缓存至用户目录下的 %USERPROFILE%\.nuget\packages。这一设计在单机开发场景下表现良好，但在团队协作或多项目并行开发时，容易导致磁盘空间浪费和版本不一致问题。

尤其在使用 PackageReference 格式或基于 .NET SDK 的项目文件（.csproj） 时，NuGet 的解析逻辑由 MSBuild 和 NuGet.Client 共同控制，路径配置不再仅依赖传统 nuget.config，而是受多个层级影响。

开发者常尝试通过设置环境变量 NUGET_PACKAGES 或修改 <config><globalPackagesFolder> 来改变存储位置，但常遇到“配置未生效”、“路径被忽略”等问题。

根本原因在于：配置优先级混乱、工具链差异、运行时上下文缺失 等因素共同作用，使得看似简单的路径变更变得复杂。

二、修改 NuGet 包路径的核心方法

以下是三种主流方式，按优先级从高到低排列：

1. 环境变量 NUGET_PACKAGES：最高优先级，适用于跨平台 CI/CD 场景。
2. nuget.config 配置 globalPackagesFolder：项目级或解决方案级控制。
3. MSBuild 属性 RestorePackagesPath：针对特定构建流程定制。

方法	适用范围	优先级	持久性	CI/CD 友好度
NUGET_PACKAGES 环境变量	全局	最高	会话级	⭐⭐⭐⭐⭐
globalPackagesFolder in nuget.config	用户/解决方案/项目	中等	文件级	⭐⭐⭐☆
RestorePackagesPath in .csproj	项目级	低	编译时	⭐⭐

三、配置优先级与作用域详解

NuGet 遵循“最近优先”原则，配置来源包括：

• 环境变量
• 项目目录下的 nuget.config
• 父目录链中的 nuget.config
• 用户目录：%APPDATA%\NuGet\NuGet.Config
• 全局配置：%ProgramFiles%\NuGet\Config\

当多个配置共存时，环境变量 NUGET_PACKAGES 优先于所有 config 文件中的 globalPackagesFolder 设置。这意味着即使你在 nuget.config 中指定了路径，若存在该环境变量，则会被覆盖。

示例代码如下：

# Windows
set NUGET_PACKAGES=D:\SharedNuGetPackages

# Linux/macOS
export NUGET_PACKAGES=/mnt/shared/nuget/packages

在 CI/CD 中建议使用脚本提前设置此变量，确保构建节点一致性。

四、常见失效场景分析与排查流程

graph TD
    A[开始] --> B{是否设置了 NUGET_PACKAGES?}
    B -- 是 --> C[检查路径权限与可写性]
    B -- 否 --> D[查找 nearest nuget.config]
    D --> E{包含 globalPackagesFolder?}
    E -- 是 --> F[验证路径是否存在且可访问]
    E -- 否 --> G[回退到默认路径]
    C --> H[执行 nuget restore 或 dotnet restore]
    F --> H
    H --> I{包是否安装到预期路径？}
    I -- 否 --> J[检查 MSBuild 并行构建冲突]
    I -- 是 --> K[成功]
    J --> L[禁用并行恢复或锁定目录]

五、实战配置案例：统一团队共享包路径

假设团队希望将所有 NuGet 包集中存储于网络映射盘 Z:\NuGetCache，需执行以下步骤：

1. 在每台开发机或构建代理上创建共享目录并赋权。
2. 设置系统环境变量：
   NUGET_PACKAGES = Z:\NuGetCache
3. 在解决方案根目录添加 nuget.config 作为备份：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <config>
    <add key="globalPackagesFolder" value="Z:\NuGetCache" />
  </config>
</configuration>

该配置可在 Git 中提交，作为文档化约定，防止环境变量遗漏。

此外，在 Azure DevOps Pipeline 中可通过任务前置设置：

steps:
- task: CmdLine@2
  inputs:
    script: |
      setx NUGET_PACKAGES "Z:\NuGetCache"

六、高级注意事项与最佳实践

尽管路径重定向可行，但仍需注意以下陷阱：

• 路径长度限制：Windows MAX_PATH 为 260 字符，深层嵌套包可能触发异常，建议使用短路径如 D:\npkgs。
• 并发写入风险：多项目同时还原可能导致锁竞争，推荐启用 <RestoreLockedMode>true</RestoreLockedMode>。
• Docker 容器化构建：应挂载卷并预设环境变量，避免每次重建下载全量包。
• .NET SDK 版本差异：.NET 6+ 对 package 缓存处理更严格，某些旧 config 可能被忽略。

可通过命令行验证当前解析路径：

dotnet nuget locals all --list

输出示例：

http-cache: C:\Users\dev\AppData\Local\NuGet\v3-cache
global-packages: Z:\NuGetCache
temp: C:\Users\dev\AppData\Local\Temp\NuGetScratch

确认 global-packages 指向目标路径即表示生效。