开发与生产环境NuGet配置文件冲突问题求助

我负责的.NET项目采用本地开发构建+CI/CD远程生产构建的模式：

• 项目根目录下的myproject/nuget.config（项目级配置）用于CI/CD环境，依赖流水线提供的环境变量获取私有源凭据
• 本地机器的~/.nuget/NuGet/NuGet.Config（用户级配置）存储了个人私有源凭据，其余配置和项目级一致

项目级配置内容 #

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="custom" value="https://example.com/api/nuget/index.json" />
  </packageSources>

  <packageSourceCredentials>
    <custom>
      <!-- 流水线提供的环境变量 -->
      <add key="Username" value="%USERNAME%" />
      <add key="ClearTextPassword" value="%API_KEY%" />
    </custom>
  </packageSourceCredentials>

  <packageSourceMapping>
    <!-- 从nuget.org获取第三方包 -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <!-- 从私有源获取内部包 -->
    <packageSource key="custom">
      <package pattern="MyOrg.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

本地用户级凭据配置 #

<packageSourceCredentials>
  <custom>
    <add key="Username" value="my_username" />
    <add key="ClearTextPassword" value="my_personal_api_key" />
  </custom>
</packageSourceCredentials>

问题 #

CI/CD环境下配置正常工作，但本地运行dotnet restore等命令时会出现401未授权错误。原因是NuGet的配置优先级为项目级 > 用户级，项目级中依赖环境变量的凭据配置覆盖了用户级的个人凭据。我不想通过导出环境变量或修改.bashrc的方式解决（涉及多个仓库，操作繁琐）。

解决方案 #

方案1：移除项目级配置中的凭据节点（推荐） #

项目级nuget.config只保留包源定义和包源映射，移除<packageSourceCredentials>节点：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="custom" value="https://example.com/api/nuget/index.json" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="custom">
      <package pattern="MyOrg.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

• 本地环境：自动使用用户级配置中的凭据，无需额外操作
• CI/CD环境：在流水线中通过命令行参数传递凭据，示例：

  dotnet restore --source "https://example.com/api/nuget/index.json" --username "$USERNAME" --password "$API_KEY"
  

方案2：使用条件配置控制凭据加载 #

利用NuGet配置的condition属性，仅在CI环境下加载项目级的凭据配置，本地环境自动 fallback 到用户级凭据：
修改项目级nuget.config的<packageSourceCredentials>部分：

<packageSourceCredentials>
  <custom>
    <!-- 仅当CI环境变量存在且为true时生效 -->
    <add key="Username" value="%USERNAME%" condition="'%CI%' == 'true'" />
    <add key="ClearTextPassword" value="%API_KEY%" condition="'%CI%' == 'true'" />
  </custom>
</packageSourceCredentials>

• 本地环境：因为没有CI环境变量（或值不为true），这两个凭据配置不会生效，NuGet会使用用户级的凭据
• CI/CD环境：流水线通常会自动设置CI=true环境变量，此时项目级的凭据配置正常加载

方案3：使用本地私有配置文件 #

在项目目录下创建nuget.local.config（添加到.gitignore避免提交），内容为本地凭据配置：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSourceCredentials>
    <custom>
      <add key="Username" value="my_username" />
      <add key="ClearTextPassword" value="my_personal_api_key" />
    </custom>
  </packageSourceCredentials>
</configuration>

然后在项目级nuget.config末尾添加引用：

<include src="nuget.local.config" />

这样本地构建时会加载私有配置，CI/CD环境因为没有这个文件，会使用环境变量凭据。此方案需要每个仓库单独配置，适合仓库数量较少的场景。

内容的提问来源于stack exchange，提问作者lonix