React+Vite+Tailwind项目Docker部署后CSS不生效问题排查

1. Vite base路径配置错误 #

Vite构建默认以/作为基准路径，若Nginx部署路径非根目录（如域名子路径），或Docker内静态文件实际存放路径与页面引用路径不匹配，会导致CSS文件引用失效（即便文件存在，也会因路径错误无法加载）。

修正方法：
在vite.config.js中显式配置base路径：根目录部署时设为'/'，子路径部署时替换为对应路径（如'/app/'）。示例：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/' // 根目录部署用此配置，子场景替换为实际路径
})

2. Nginx配置问题 #

常见错误包括静态文件根目录指向错误、未正确匹配静态资源请求，或MIME类型处理异常。

错误示例（路径嵌套问题）： #

server {
  listen 80;
  root /usr/share/nginx/html/dist; # 错误：将dist文件夹作为根目录，导致页面引用的/css/main.css实际路径为/dist/css/main.css
  location / {
    try_files $uri $uri/ /index.html;
  }
}

正确配置： #

确保Nginx root指向存放dist文件的目录，并正确处理静态资源：

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

  # 静态资源缓存配置，同时确保MIME类型正确
  location ~* \.(css|js|png|jpg|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }

  # SPA路由 fallback
  location / {
    try_files $uri $uri/ /index.html;
  }
}

3. Dockerfile构建步骤错误 #

若Dockerfile未正确复制dist目录内的文件，而是将整个dist文件夹复制到Nginx目录，会导致路径嵌套，引发资源引用错误。

错误示例： #

FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html/dist # 错误：将dist文件夹放入，导致路径多一层
COPY nginx.conf /etc/nginx/conf.d/default.conf

正确Dockerfile： #

复制dist目录内的所有文件到Nginx静态根目录：

FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production # 用ci安装确保依赖版本一致，仅装生产依赖
COPY . .
RUN npm run build

FROM nginx:alpine
# 复制dist下所有文件到Nginx根目录
COPY --from=builder /app/dist/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf

4. 快速验证方法 #

进入容器内部，用curl测试CSS文件是否可正常访问：

# 进入容器
docker exec -it <容器ID> sh
# 测试页面引用的CSS路径，示例：
curl http://localhost/css/main.css

若返回404，说明路径匹配错误，检查Nginx的root和location配置；若返回CSS内容，说明页面引用路径问题，检查Vite的base配置。同时可查看Nginx日志（容器内路径/var/log/nginx/access.log和error.log）定位具体错误。

额外部署建议 #

• 构建阶段使用npm ci替代npm install，确保依赖版本一致，避免构建差异。
• 给静态资源设置缓存策略，如Nginx配置中的expires和Cache-Control，提升访问性能。
• 部署前本地执行npm run build，检查dist目录结构，确认CSS文件在预期路径（如dist/css/）。

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