React.js(v18.2.0)部署后页面空白及MIME类型错误求助

1. 服务器路由Fallback配置错误（核心排查点） #

这个错误本质是本该请求JS模块的请求，被服务器返回了index.html文件（MIME为text/html）。当使用React客户端路由时，服务器需要优先返回静态资源，只有非静态路径才fallback到index.html。如果这个逻辑颠倒或覆盖范围错误，就会偶尔触发问题：

• 若用Nginx，检查配置是否优先匹配静态资源：

# 先匹配静态资源，命中则直接返回
location ~* \.(js|css|png|svg|woff2)$ {
  root /usr/share/nginx/html;
  expires 1y;
  add_header Cache-Control "public, immutable";
}
# 非静态路径才fallback到index.html
location / {
  try_files $uri $uri/ /index.html;
}

• 若用Node.js服务器（如Express），确保express.static在路由中间件之前加载：

app.use(express.static('dist'));
// 客户端路由fallback
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist/index.html'));
});

2. Docker部署的路径与权限问题 #

Docker构建后静态资源的实际路径可能和服务器预期不匹配，导致服务器找不到文件，返回index.html：

• 检查Dockerfile中dist目录的复制路径是否正确，比如Nginx默认根目录是/usr/share/nginx/html，确保COPY命令对应：

FROM nginx:alpine
COPY ./dist /usr/share/nginx/html

• 进入容器检查静态文件权限，确保服务器进程（如nginx用户）有权限读取这些文件：

docker exec -it <container-id> ls -l /usr/share/nginx/html/assets

3. Vite构建的Base路径配置 #

Vite的base参数决定了静态资源的请求根路径，配置错误会导致资源请求地址无效：

• 在vite.config.js中确认base与实际部署路径一致：根路径部署用base: '/'，子路径部署（如https://example.com/my-app/）用base: '/my-app/'：

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

export default defineConfig({
  plugins: [react()],
  base: '/', // 按实际部署路径调整
  build: {
    // 保留你的其他配置
  }
});

4. 浏览器缓存与资源Hash冲突 #

Vite默认会给构建后的资源加Hash（如app.abc123.js），但如果index.html被缓存，可能导致旧页面引用已删除的资源，触发服务器返回index.html：

• 确保服务器配置中，index.html不被缓存（添加Cache-Control: no-cache），而静态资源开启强缓存：

location = /index.html {
  add_header Cache-Control "no-cache";
}

5. CI/CD构建的资源路径篡改 #

如果CI/CD流程中有修改dist/index.html的步骤（如替换环境变量），可能误改了资源引用路径，导致请求地址错误：

• 检查CI/CD脚本中的替换逻辑，确保仅替换环境变量等动态内容，不修改静态资源的路径字符串。

推荐搜索关键词 #

• Vite build MIME type text/html module script
• React Router Docker static asset fallback
• Nginx Vite MIME type mismatch
• Client-side routing server fallback issue

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