使用Docker部署ABP.io Blazor WASM遇问题：Nginx显示默认页（.NET 8）

问题背景 #

使用Docker部署ABP.io Blazor WebAssembly应用，严格遵循官方部署文档操作，但部署后Nginx始终显示默认页，无法加载Blazor应用。核心问题是.NET 8环境下Blazor.Client项目发布后，Nginx根目录缺少index.html文件。

用到的Dockerfile及命令 #

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS build
COPY bin/Release/net8.0/publish/ app/
  
FROM nginx:alpine-slim AS final
WORKDIR /usr/share/nginx/html
COPY --from=build /app/wwwroot .
COPY /nginx.conf  /etc/nginx/conf.d/default.conf

dotnet publish -c Release -p:PublishTrimmed=false 
docker build -f Dockerfile.local -t acme/bookstore-blazor:latest .

现象截图 #

解决方案 #

1. 确认本地发布输出的正确性 #

.NET 8 Blazor WASM项目发布后，默认会在bin/Release/net8.0/publish/wwwroot下生成index.html，如果没有，检查以下几点：

• 确认项目是Blazor WebAssembly客户端项目（而非Blazor Server）
• 执行dotnet publish时，需指定具体的Client项目文件，避免发布错误项目：

  dotnet publish Acme.BookStore.Blazor.csproj -c Release -p:PublishTrimmed=false
  

• 如果本地项目根目录的wwwroot下就没有index.html，右键项目→添加→新建项→选择「HTML页面」，命名为index.html，并添加Blazor WASM基础结构：

  <!DOCTYPE html>
  <html>
  <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Acme BookStore</title>
      <base href="/" />
      <link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />
      <link href="css/site.css" rel="stylesheet" />
      <link href="Acme.BookStore.Blazor.styles.css" rel="stylesheet" />
  </head>
  <body>
      <div id="app">Loading...</div>
      <div id="blazor-error-ui">
          An unhandled error has occurred.
          <a href="" class="reload">Reload</a>
          <a class="dismiss">🗙</a>
      </div>
      <script src="_framework/blazor.webassembly.js"></script>
  </body>
  </html>
  

2. 修正Dockerfile的构建逻辑 #

原Dockerfile第一阶段使用ASP.NET Runtime镜像属于冗余操作——Blazor WASM是静态文件，不需要.NET Runtime。推荐直接在Docker内完成构建，避免本地环境差异：

# 构建阶段：用SDK编译发布项目
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
# 先复制项目文件，利用Docker缓存加速构建
COPY ["Acme.BookStore.Blazor/Acme.BookStore.Blazor.csproj", "Acme.BookStore.Blazor/"]
RUN dotnet restore "Acme.BookStore.Blazor/Acme.BookStore.Blazor.csproj"
# 复制所有代码
COPY . .
WORKDIR "/src/Acme.BookStore.Blazor"
# 发布到指定目录
RUN dotnet publish -c Release -o /app/publish -p:PublishTrimmed=false

# 运行阶段：用Nginx托管静态文件
FROM nginx:alpine-slim AS final
WORKDIR /usr/share/nginx/html
# 复制发布后的wwwroot内容到Nginx根目录
COPY --from=build /app/publish/wwwroot .
# 复制自定义Nginx配置（确保路径与项目结构匹配）
COPY Acme.BookStore.Blazor/nginx.conf /etc/nginx/conf.d/default.conf

3. 配置Nginx支持SPA路由 #

Nginx默认不处理SPA前端路由，需修改nginx.conf，确保刷新页面不会404，同时默认指向index.html：

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # 所有请求转发到index.html，支持Blazor路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 开启gzip压缩，提升加载速度
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/javascript application/javascript application/json;
}

4. 验证并重新部署 #

• 本地发布后，确认publish/wwwroot目录下存在index.html
• 构建镜像后，临时运行容器检查文件是否复制成功：

  docker run --rm -it acme/bookstore-blazor:latest ls /usr/share/nginx/html
  

  看到输出包含index.html即说明复制正确
• 重新运行容器：

  docker run -d -p 8080:80 acme/bookstore-blazor:latest
  

  访问http://localhost:8080即可加载Blazor应用。

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