Mac构建.NET8 API Alpine Docker镜像时runtimeconfig.json无效报错

问题场景 #

在M1 Mac（Sonoma 14.5）上构建部署到Cloud Run的.NET 8 API Docker镜像时，执行命令：

docker build . -t testapi:alpine-secure-test-runtime -f Dockerfile-TestAPI

在RUN dotnet restore环节触发报错，提示/usr/share/dotnet/sdk/8.0.303/dotnet.runtimeconfig.json文档为空、文件无效。实际.NET SDK安装路径为/usr/local/share/dotnet/sdk/8.0.303/，与系统期望路径不匹配；且仅在使用Alpine镜像构建.NET 8时出现此问题，.NET 6或.NET 8自动生成的Dockerfile无异常。

解决方案 #

1. 改用官方.NET 8 Alpine SDK基础镜像 #

官方镜像已正确配置.NET路径环境变量，避免自定义镜像的路径混乱问题。调整Dockerfile构建阶段：

FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
WORKDIR /src

COPY ["YourApi.csproj", "."]
# 无需额外配置路径，直接执行restore
RUN dotnet restore "./YourApi.csproj"

# 后续的构建、发布步骤...

2. 显式指定DOTNET_ROOT环境变量 #

如果必须使用自定义基础镜像，在执行dotnet restore前添加环境变量配置，强制指定正确的SDK路径：

# 构建阶段开头添加
ARG DOTNET_ROOT=/usr/local/share/dotnet
ENV DOTNET_ROOT=${DOTNET_ROOT}
ENV PATH="${DOTNET_ROOT}/bin:${PATH}"

# 再执行restore
RUN dotnet restore

3. 清理Docker缓存与Scout数据 #

.docker/scout/sbom/目录下的旧路径缓存可能干扰构建，执行以下操作清理：

# 清理所有构建缓存
docker builder prune -af
# 删除Scout的SBOM缓存目录
rm -rf .docker/scout

清理完成后重新执行构建命令。

4. 确保多平台构建的架构适配 #

M1 Mac为ARM64架构，构建时需明确指定平台参数，避免架构不兼容导致的路径异常：

• 在Dockerfile开头添加平台声明：

ARG TARGETPLATFORM=linux/arm64
FROM --platform=${TARGETPLATFORM} mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build

• 或构建时通过命令行指定：

docker build --platform linux/arm64 . -t testapi:alpine-secure-test-runtime -f Dockerfile-TestAPI

5. 对比官方自动生成的Dockerfile #

将你的自定义Dockerfile与dotnet new dockerfile生成的.NET 8版本对比，重点检查：

• 基础镜像的版本和类型
• 环境变量的配置项
• dotnet restore的执行参数与上下文

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