如何解决打包报错：Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of “text/html”

💡作者： AI前端Web万粉变现经纪人
📅发布日期：2025-11-04
📚标签：前端报错、打包错误、Vite、Webpack、部署问题

如何解决打包报错：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。

修复步骤

1. 修改 vite.config.js：

   export default defineConfig({
     base: './'
   })
   

2. 重新打包：

   npm run build
   

3. 检查 dist 目录完整上传。

4. 配置 Nginx：

   server {
       listen 80;
       server_name yourdomain.com;
       root /var/www/html/dist;
   
       location / {
           try_files $uri $uri/ /index.html;
       }
   }
   

5. 重启 nginx：

   sudo nginx -s reload
   

✅ 问题解决！

---

🧰 六、总结

原因类型	表现	解决方案
JS 文件路径错误	加载 404 HTML 页面	检查 publicPath / base
部署目录错误	缺失 assets 文件夹	确保完整上传
前端路由 history 模式	JS 请求被路由覆盖	配置 nginx fallback
MIME 类型错误	返回 text/html	设置 application/javascript
type="module" 使用不当	路径指向错误	检查引用路径

---

💬 七、结语

这种错误看似复杂，但本质上是浏览器加载了错误的文件类型。
通过逐步排查路径、部署、服务器配置，你一定能快速定位问题。

如果你在部署中遇到了相似的报错，也欢迎在评论区分享你的解决方案，一起完善这篇文章 ❤️

---

🧡 如果这篇文章对你有帮助，请一键三连（👍点赞 + 💬评论 + ⭐收藏），
这会是我持续输出优质技术博客的最大动力！

---