macOS跨平台构建Linux/amd64镜像时dotnet tool restore失败

问题场景 #

在macOS环境下执行docker build --platform linux/amd64 -t dotnet_tools_issue .构建基于.NET 8 Alpine的镜像时，dotnet tool restore步骤抛出如下异常：

Unhandled exception:Newtonsoft.Json.JsonSerializationException: Unable to find a constructor to use for type NuGet.Protocol.Model.RegistrationIndex. A class should either have a default constructor, one constructor with arguments or a constructor marked with the JsonConstructor attribute. Path '@id', line 1, position 7.

解决方案 #

1. 升级Docker Desktop（修复QEMU模拟问题） #

旧版本Docker Desktop的QEMU在模拟x86_64架构时存在兼容性bug，会导致.NET工具的NuGet序列化操作出错。直接升级到最新版Docker Desktop，重启后再尝试构建。

2. 更换.NET SDK镜像或补充Alpine依赖 #

Alpine的轻量镜像可能缺少.NET组件依赖，或者在跨平台模拟时更容易出问题：

• 方案A：改用Debian基础的SDK镜像
  修改Dockerfile的基础镜像：

  FROM mcr.microsoft.com/dotnet/sdk:8.0 AS base
  

• 方案B：补充Alpine依赖并开启全球化支持
  如果坚持用Alpine，添加ICU依赖并设置环境变量：

  FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS base
  ENV ASPNETCORE_ENVIRONMENT=Production
  ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false
  RUN export PATH="$PATH:/root/.dotnet/tools"
  RUN apk add --update --no-cache libintl libxml2-utils bc icu-libs
  

3. 调整dotnet tool restore命令 #

指定官方NuGet源或禁用缓存，避免源或缓存损坏的问题：

# 指定官方源
RUN dotnet tool restore --source https://api.nuget.org/v3/index.json

# 或禁用缓存强制拉取
RUN dotnet tool restore --no-cache

4. 清理Docker缓存 #

本地缓存的基础镜像或中间层可能损坏，执行以下命令清理后重新构建：

docker system prune -af

5. 使用Docker Buildx构建 #

Buildx对跨平台构建的支持更完善，执行以下命令：

# 创建并使用Buildx builder
docker buildx create --use
# 构建并加载到本地Docker
docker buildx build --platform linux/amd64 -t dotnet_tools_issue . --load

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