Docker+Nginx部署React应用时CSS无法加载的问题排查

1. 检查Nginx静态资源配置 #

确保nginx.conf的路径映射和路由规则正确，这是最常见的问题根源：

server {
    listen 80;
    server_name localhost;

    # 指向容器内React build产物的目录
    root /usr/share/nginx/html;
    index index.html index.htm;

    # 单页应用路由 fallback，同时确保静态资源能被正确匹配
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 明确处理静态资源，避免MIME类型错误或缓存异常
    location ~* \.(css|js|png|jpg|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

注意点：

• root必须和Dockerfile中复制build产物的目标路径完全一致
• 必须保留try_files规则，否则不仅路由会失效，静态资源也可能无法被正确解析
• 不要添加多余的rewrite规则导致CSS路径被错误重定向

2. 验证Dockerfile构建流程 #

确保构建阶段正确生成并复制了完整的build产物：

# 构建阶段
FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build # 生成带哈希命名的静态资源

# 部署阶段
FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
# 把build产物复制到Nginx默认静态目录
COPY --from=builder /app/build /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

排查点：

• 确认构建阶段执行了npm run build而非npm run dev
• 进入容器检查/usr/share/nginx/html/static/css目录是否存在，且包含正确的CSS文件
• 避免遗漏复制build文件夹到Nginx镜像的步骤

3. 解决304缓存导致的样式不生效 #

Nginx返回304说明浏览器复用了旧缓存，可通过以下方式修复：

• 强制刷新页面：按Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）跳过缓存
• 利用create-react-app的哈希命名特性：build后的CSS/JS文件名自带唯一哈希（如main.abc123.css），配合Nginx的immutable缓存头，确保新部署的资源不会被旧缓存覆盖
• 测试阶段可临时禁用Nginx缓存：在location ~* \.(css|js)$中添加add_header Cache-Control "no-cache";

4. 检查index.html的CSS引入路径 #

本地build后打开index.html，确认CSS的引入路径是相对根路径（如<link href="/static/css/main.abc123.css" rel="stylesheet">）：

• 如果应用部署在子路径下（如/my-app），构建时需指定PUBLIC_URL：PUBLIC_URL=/my-app npm run build，同时Nginx配置要对应修改：

location /my-app {
    root /usr/share/nginx/html;
    try_files $uri $uri/ /my-app/index.html;
}

5. 排查容器内权限与日志 #

• 查看Nginx错误日志：docker exec <容器ID> cat /var/log/nginx/error.log，排查是否存在文件权限不足或路径不存在的错误
• 给静态文件添加正确权限：在Dockerfile部署阶段添加RUN chown -R nginx:nginx /usr/share/nginx/html，确保Nginx用户能读取静态资源

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