vue.js

关注公众号 jb51net

关闭
首页 > 网络编程 > JavaScript > javascript类库 > vue.js > Vue3静态文件打包404

Vue3静态文件打包404的解决方案

作者：实习生小黄

在 Vue3 + Vite 项目开发过程中,经常会遇到静态资源文件在开发环境正常,但打包后出现 404 错误的问题,本文通过一个实际案例——引入 MarchingSquares.js 库的过程,详细分析问题的原因和解决方案,需要的朋友可以参考下

前言

在 Vue3 + Vite 项目开发过程中，经常会遇到静态资源文件（如第三方 JS 库、图片、字体等）在开发环境正常，但打包后出现 404 错误的问题。本文通过一个实际案例——引入 MarchingSquares.js 库的过程，详细分析问题的原因和解决方案。

问题背景

项目中需要使用 MarchingSquares.js 这个第三方库，该库需要在 HTML 中通过 <script> 标签直接引入。在开发过程中，我们尝试了多种路径配置方式，但都遇到了不同的问题：

解决方案

尝试一：使用相对路径./MarchingSquaresJS/MarchingSquares.js

配置方式：

<script type="text/javascript" src="./MarchingSquaresJS/MarchingSquares.js"></script>

结果：

原因分析：

  1. Vite 只会处理在代码中通过 import 导入的资源，对于 HTML 中直接引用的静态资源，Vite 不会自动处理
  2. 如果文件不在 public 目录下，Vite 在打包时不会将其复制到 dist 目录
  3. 相对路径 ./ 在 HTML 中解析时，会基于当前 HTML 文件的位置，但打包后的文件结构可能不同

尝试二：移动到 public 目录并使用./public/MarchingSquaresJS/MarchingSquares.js

配置方式：

<script type="text/javascript" src="./public/MarchingSquaresJS/MarchingSquares.js"></script>

结果：

原因分析：

  1. Vite 会将 public 目录下的文件原样复制到 dist 目录的根目录，但不会保留 public 这个目录名
  2. 例如：public/MarchingSquaresJS/MarchingSquares.js → dist/MarchingSquaresJS/MarchingSquares.js
  3. 但 HTML 中写的是 ./public/MarchingSquaresJS/MarchingSquares.js，浏览器会尝试访问 dist/public/MarchingSquaresJS/MarchingSquares.js，这个路径不存在

最终方案一：使用绝对路径/MarchingSquaresJS/MarchingSquares.js

配置方式：

<script type="text/javascript" src="/MarchingSquaresJS/MarchingSquares.js"></script>

结果：

原因分析：

  1. 以 / 开头的路径是绝对路径，相对于网站根目录
  2. Vite 会将 public 目录下的文件复制到 dist 根目录，所以 public/MarchingSquaresJS/ → dist/MarchingSquaresJS/
  3. 使用 /MarchingSquaresJS/MarchingSquares.js 可以正确访问到 dist/MarchingSquaresJS/MarchingSquares.js
  4. 在开发环境中，Vite 的 dev server 也会将 public 目录作为静态资源根目录，所以同样可以访问

局限性：

最终方案二：使用BASE_URL模板变量（推荐）

配置方式：

<script type="text/javascript" src="<%- BASE_URL %>MarchingSquaresJS/MarchingSquares.js"></script>

结果：

原因分析：

  1. BASE_URL 是 vite-plugin-html 插件提供的模板变量
  2. 它的值自动等于 Vite 配置中的 base 选项值
  3. 当 base: '/' 时，BASE_URL = '/'
  4. 当 base: '/app/' 时，BASE_URL = '/app/'
  5. 这样可以根据部署路径自动调整资源路径，无需手动修改 HTML

优势：

原理

Vite 的 public 目录机制

Vite 对 public 目录有特殊的处理规则：

开发环境（dev）：

生产环境（build）：

路径解析规则

在 HTML 中，路径的解析方式如下：

路径格式解析方式示例
/path/to/file.js绝对路径，相对于网站根目录http://localhost:3000/path/to/file.js
./path/to/file.js相对路径，相对于当前 HTML 文件所在目录如果 HTML 在 /，则解析为 /path/to/file.js
../path/to/file.js相对路径，相对于当前 HTML 文件的父目录如果 HTML 在 /sub/，则解析为 /path/to/file.js
path/to/file.js相对路径，等同于 ./path/to/file.js同上

为什么绝对路径/可以工作？

开发环境：

生产环境：

Vite 配置

base 配置的作用

在 vite.config.ts 中，base 选项用于设置应用的公共基础路径：

export default defineConfig({
  base: '/',  // 默认值，应用部署在根目录
  // 或者
  base: '/app/',  // 应用部署在子目录
})

作用：

影响打包后的资源路径：

影响 HTML 中的路径解析：

总结

关键要点

静态资源必须放在 public 目录：

使用绝对路径 / 或 BASE_URL 而不是相对路径：

base 配置的作用：

BASE_URL 的优势：

开发和生产环境的一致性：

推荐配置

方案一：使用绝对路径（适合固定部署在根目录）

<!-- index.html -->
<script type="text/javascript" src="/MarchingSquaresJS/MarchingSquares.js"></script>

// vite.config.ts
export default defineConfig({
  base: '/',  // 固定部署在根目录
  // ... 其他配置
})

方案二：使用 BASE_URL（推荐，支持灵活部署）

<!-- index.html -->
<script type="text/javascript" src="<%- BASE_URL %>MarchingSquaresJS/MarchingSquares.js"></script>

// vite.config.ts
export default defineConfig({
  base: isProd ? APP_BASE_PATH : '/',  // 根据实际部署路径调整
  plugins: [
    // ... 其他插件
    createHtmlPlugin({
      minify: isProd,
      inject: {
        data: {
          title: APP_TITLE,
          // BASE_URL 会自动等于 base 的值，无需手动设置
        },
      },
    }),
  ],
  // ... 其他配置
})

对比：

方案优点缺点适用场景
绝对路径 /简单直接不支持子目录部署固定部署在根目录
BASE_URL自动适配部署路径需要了解模板语法需要支持多环境部署

以上就是Vue3静态文件打包404的解决方案的详细内容，更多关于Vue3静态文件打包404的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:
阅读全文