前言

在 Vue3 + Vite 項(xiàng)目開發(fā)過程中，經(jīng)常會遇到靜態(tài)資源文件（如第三方 JS 庫、圖片、字體等）在開發(fā)環(huán)境正常，但打包后出現(xiàn) 404 錯(cuò)誤的問題。本文通過一個(gè)實(shí)際案例——引入 MarchingSquares.js 庫的過程，詳細(xì)分析問題的原因和解決方案。

問題背景

項(xiàng)目中需要使用 MarchingSquares.js 這個(gè)第三方庫，該庫需要在 HTML 中通過 <script> 標(biāo)簽直接引入。在開發(fā)過程中，我們嘗試了多種路徑配置方式，但都遇到了不同的問題：

• 使用相對路徑 ./MarchingSquaresJS/MarchingSquares.js：打包后文件不存在
• 使用 ./public/MarchingSquaresJS/MarchingSquares.js：打包后文件存在，但訪問時(shí) 404
• 最終使用 /MarchingSquaresJS/MarchingSquares.js：開發(fā)和生產(chǎn)環(huán)境都正常

解決方案

嘗試一：使用相對路徑./MarchingSquaresJS/MarchingSquares.js

配置方式：

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

結(jié)果：

• ? 打包后 dist 目錄下不存在 MarchingSquaresJS 文件夾
• ? 文件無法被訪問

原因分析：

1. Vite 只會處理在代碼中通過 import 導(dǎo)入的資源，對于 HTML 中直接引用的靜態(tài)資源，Vite 不會自動處理
2. 如果文件不在 public 目錄下，Vite 在打包時(shí)不會將其復(fù)制到 dist 目錄
3. 相對路徑 ./ 在 HTML 中解析時(shí)，會基于當(dāng)前 HTML 文件的位置，但打包后的文件結(jié)構(gòu)可能不同

嘗試二：移動到 public 目錄并使用./public/MarchingSquaresJS/MarchingSquares.js

配置方式：

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

結(jié)果：

• ? 打包后 dist 目錄下出現(xiàn)了 MarchingSquaresJS/MarchingSquares.js 文件
• ? 訪問打包后的頁面時(shí)，瀏覽器嘗試訪問 ./public/MarchingSquaresJS/MarchingSquares.js，出現(xiàn) 404 錯(cuò)誤

原因分析：

1. Vite 會將 public 目錄下的文件原樣復(fù)制到 dist 目錄的根目錄，但不會保留 public 這個(gè)目錄名
2. 例如：public/MarchingSquaresJS/MarchingSquares.js → dist/MarchingSquaresJS/MarchingSquares.js
3. 但 HTML 中寫的是 ./public/MarchingSquaresJS/MarchingSquares.js，瀏覽器會嘗試訪問 dist/public/MarchingSquaresJS/MarchingSquares.js，這個(gè)路徑不存在

最終方案一：使用絕對路徑/MarchingSquaresJS/MarchingSquares.js

配置方式：

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

結(jié)果：

• ? 開發(fā)環(huán)境（npm run dev）正常訪問
• ? 生產(chǎn)環(huán)境（打包后）正常訪問（前提是部署在根目錄）

原因分析：

1. 以 / 開頭的路徑是絕對路徑，相對于網(wǎng)站根目錄
2. Vite 會將 public 目錄下的文件復(fù)制到 dist 根目錄，所以 public/MarchingSquaresJS/ → dist/MarchingSquaresJS/
3. 使用 /MarchingSquaresJS/MarchingSquares.js 可以正確訪問到 dist/MarchingSquaresJS/MarchingSquares.js
4. 在開發(fā)環(huán)境中，Vite 的 dev server 也會將 public 目錄作為靜態(tài)資源根目錄，所以同樣可以訪問

局限性：

• 如果應(yīng)用部署在子目錄（如 /app/），硬編碼的 /MarchingSquaresJS/... 路徑會失效
• 需要手動根據(jù)部署路徑修改 HTML 中的路徑

最終方案二：使用BASE_URL模板變量（推薦）

配置方式：

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

結(jié)果：

• ? 開發(fā)環(huán)境（npm run dev）正常訪問
• ? 生產(chǎn)環(huán)境（打包后）正常訪問
• ? 支持部署到任意路徑（根目錄或子目錄）

原因分析：

1. BASE_URL 是 vite-plugin-html 插件提供的模板變量
2. 它的值自動等于 Vite 配置中的 base 選項(xiàng)值
3. 當(dāng) base: '/' 時(shí)，BASE_URL = '/'
4. 當(dāng) base: '/app/' 時(shí)，BASE_URL = '/app/'
5. 這樣可以根據(jù)部署路徑自動調(diào)整資源路徑，無需手動修改 HTML

優(yōu)勢：

• 自動適配不同的部署路徑
• 與 Vite 的 base 配置保持一致
• 無需手動維護(hù)路徑，減少出錯(cuò)概率

原理

Vite 的 public 目錄機(jī)制

Vite 對 public 目錄有特殊的處理規(guī)則：

開發(fā)環(huán)境（dev）：

• public 目錄下的文件會被映射到網(wǎng)站根路徑 /
• 例如：public/favicon.ico → http://localhost:3000/favicon.ico
• 例如：public/MarchingSquaresJS/MarchingSquares.js → http://localhost:3000/MarchingSquaresJS/MarchingSquares.js

生產(chǎn)環(huán)境（build）：

• public 目錄下的所有文件會被原樣復(fù)制到 dist 目錄的根目錄
• 不會保留 public 目錄名
• 例如：public/MarchingSquaresJS/MarchingSquares.js → dist/MarchingSquaresJS/MarchingSquares.js
• 例如：public/favicon.ico → dist/favicon.ico

路徑解析規(guī)則

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

為什么絕對路徑/可以工作？

開發(fā)環(huán)境：

• Vite dev server 將 public 目錄映射到 /
• /MarchingSquaresJS/MarchingSquares.js → public/MarchingSquaresJS/MarchingSquares.js ?

生產(chǎn)環(huán)境：

• 打包后文件在 dist/MarchingSquaresJS/MarchingSquares.js
• 如果部署在網(wǎng)站根目錄，/MarchingSquaresJS/MarchingSquares.js 直接對應(yīng) dist/MarchingSquaresJS/MarchingSquares.js ?
• 如果部署在子目錄（如 /app/），需要配置 base 選項(xiàng)（見下文）

Vite 配置

base 配置的作用

在 vite.config.ts 中，base 選項(xiàng)用于設(shè)置應(yīng)用的公共基礎(chǔ)路徑：

export default defineConfig({
  base: '/',  // 默認(rèn)值，應(yīng)用部署在根目錄
  // 或者
  base: '/app/',  // 應(yīng)用部署在子目錄
})

作用：

影響打包后的資源路徑：

• 當(dāng) base: '/' 時(shí)，所有資源路徑都是絕對路徑（如 /assets/index.js）
• 當(dāng) base: '/app/' 時(shí)，所有資源路徑會加上前綴（如 /app/assets/index.js）

影響 HTML 中的路徑解析：

• 如果 HTML 中使用絕對路徑 /path/to/file.js，且 base: '/app/'
• 實(shí)際訪問路徑會是 /app/path/to/file.js

總結(jié)

關(guān)鍵要點(diǎn)

靜態(tài)資源必須放在 public 目錄：

• 只有 public 目錄下的文件會被 Vite 復(fù)制到 dist 目錄
• public 目錄名不會出現(xiàn)在打包后的路徑中

使用絕對路徑 / 或 BASE_URL 而不是相對路徑：

• 絕對路徑 /path/to/file.js 相對于網(wǎng)站根目錄
• 相對路徑 ./path/to/file.js 可能在不同環(huán)境下解析不一致
• 推薦使用 BASE_URL，可以自動適配不同的部署路徑

base 配置的作用：

• 主要用于設(shè)置應(yīng)用的公共基礎(chǔ)路徑
• 影響打包后資源的路徑前綴
• 對于 HTML 中直接寫的絕對路徑，base 的影響有限
• BASE_URL 模板變量的值自動等于 base 配置

BASE_URL 的優(yōu)勢：

• 自動適配部署路徑（根目錄或子目錄）
• 與 Vite 的 base 配置保持一致
• 支持通過環(huán)境變量配置，無需修改代碼

開發(fā)和生產(chǎn)環(huán)境的一致性：

• 使用 / 開頭的絕對路徑或 BASE_URL，可以保證開發(fā)和生產(chǎn)環(huán)境行為一致
• Vite 的 dev server 和打包后的靜態(tài)服務(wù)器都會正確處理

推薦配置

方案一：使用絕對路徑（適合固定部署在根目錄）

<!-- 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 : '/',  // 根據(jù)實(shí)際部署路徑調(diào)整
  plugins: [
    // ... 其他插件
    createHtmlPlugin({
      minify: isProd,
      inject: {
        data: {
          title: APP_TITLE,
          // BASE_URL 會自動等于 base 的值，無需手動設(shè)置
        },
      },
    }),
  ],
  // ... 其他配置
})

對比：

以上就是Vue3靜態(tài)文件打包404的解決方案的詳細(xì)內(nèi)容，更多關(guān)于Vue3靜態(tài)文件打包404的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論