如何解决打包报错：Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of 'text/html'
最近在前端项目（如 Vite / Webpack / Vue / React 项目）中打包后部署到服务器时，浏览器控制台出现了如下报错：
Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html". Strict MIME type checking is enforced for module scripts per HTML spec.
很多同学看到这类报错第一反应可能是「JS 文件路径错误」，但实际上这个问题往往与服务器配置、路由规则、打包路径、部署目录等都有关系。
本文将带你一步步分析原因、提供多种排查思路和详细解决方案。
一、问题背景
二、错误原因解析
报错的关键在于：
'Expected a JavaScript module script but the server responded with a MIME type of text/html'
意思是：
- 浏览器期望加载的是一个 JavaScript 模块文件（.js）
- 但服务器返回的 不是 JS 文件内容，而是一个 HTML 页面
- 因为 HTML 的 MIME 类型是
text/html，浏览器拒绝将其当成 JS 模块执行
常见触发场景
| 场景 | 说明 |
|---|---|
| 1️⃣ 打包路径错误 | JS 文件路径错误，导致服务器返回 404 页面（HTML） |
| 2️⃣ 部署目录不对 | 没有正确部署 dist 目录或 build 目录 |
| 3️⃣ 服务器路由规则错误 | 前端路由（如 Vue Router、React Router）没有配置 fallback |
| 4️⃣ MIME 配置缺失 | 服务器未设置正确的 .js 文件 MIME 类型 |
5️⃣ 使用 type="module" 时访问错误 | HTML 文件引用的路径不匹配实际构建产物路径 |
三、排查步骤（逐步定位问题）
✅ 步骤 1：检查报错的 JS 文件路径
打开浏览器控制台，查看报错中的路径：
http://yourdomain.com/assets/index-xxxxx.js
然后尝试在浏览器直接访问这个地址。
👉 如果返回的是一个 HTML 页面（通常是你的 index.html），说明路径解析错误。
解决方式：
- 检查你的
<script type="module" src="...">路径是否正确 - 打包配置中是否有设置正确的
base或publicPath
例如 Vite：
// vite.config.js
export default defineConfig({
base: './', // ✅ 若部署在子目录，使用相对路径
});
例如 Webpack：
// webpack.config.js
output: {
publicPath: './', // ✅ 确保生成的路径是相对的
}
✅ 步骤 2：检查部署目录结构
打包后项目一般生成：
dist/
├── index.html
└── assets/
├── index-xxxx.js
└── style.css
如果你只部署了部分文件（例如只放了 index.html 而没放 assets 文件夹），那么访问时自然加载不到 JS 文件。
解决方式：
确保部署时完整上传：
scp -r dist/* /var/www/html/
或在 nginx 配置中正确指向：
root /var/www/html/dist;
✅ 步骤 3：检查服务端路由（单页应用常见）
如果你使用了 Vue Router / React Router，并且开启了 history 模式：
- 用户访问
/home、/about时 - 服务器其实会尝试返回
/home文件 - 结果找不到，于是返回
index.html - 浏览器误以为
/home是 JS 模块 ⇒ 报错！
解决方式：
在 nginx 中添加 fallback 配置：
location / { try_files $uri $uri/ /index.html; }
👉 这样当找不到文件时，会自动回退到 index.html，而不是返回 404 HTML 页面。
✅ 步骤 4：检查 MIME 类型设置
虽然现代服务器通常会自动设置 .js 的 MIME 类型为 application/javascript，但某些静态服务器或框架未正确配置。
Nginx 设置示例：
types {
text/html html;
application/javascript js;
text/css css;
}
Apache 示例：
在 .htaccess 文件中添加：
AddType application/javascript .js
✅ 步骤 5：确认 type="module" 的使用正确
在 HTML 中引用 JS 时：
<script type="module" src="/assets/index.js"></script>
确保该路径存在。如果你不需要 ES Module 形式，也可以移除 type="module" 进行测试：
<script src="/assets/index.js"></script>
如果此时加载正常，则说明问题确实与 模块脚本路径 有关。
四、常见框架中的对应解决方案
✅ Vite 项目部署到子路径
在 vite.config.js 中设置正确的 base：
export default defineConfig({
base: '/my-app/', // 若部署在 yourdomain.com/my-app/
});
✅ React 项目（Create React App）
在 package.json 中添加：
"homepage": "https://yourdomain.com/my-app"
然后重新打包：
npm run build
✅ Vue CLI 项目
在 vue.config.js 中：
module.exports = {
publicPath: './'
}
五、一个完整的示例修复过程
假设你的项目是用 Vite + Vue3 开发的，部署到 Nginx，访问时报错。
问题现象
浏览器报错：
Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"
打开 Network 面板发现： /assets/index-xxxxx.js 返回的是 index.html。
修复步骤
- 检查
dist目录完整上传。
重启 nginx：
sudo nginx -s reload
配置 Nginx：
server {
listen 80;
server_name yourdomain.com;
root /var/www/html/dist;
location / {
try_files $uri $uri/ /index.html;
}
}
重新打包：
npm run build
修改 vite.config.js：
export default defineConfig({
base: './'
})
✅ 问题解决！
六、总结
| 原因类型 | 表现 | 解决方案 |
|---|---|---|
| JS 文件路径错误 | 加载 404 HTML 页面 | 检查 publicPath / base |
| 部署目录错误 | 缺失 assets 文件夹 | 确保完整上传 |
| 前端路由 history 模式 | JS 请求被路由覆盖 | 配置 nginx fallback |
| MIME 类型错误 | 返回 text/html | 设置 application/javascript |
type="module" 使用不当 | 路径指向错误 | 检查引用路径 |
