Vue 靜態託管

部署你的
Vue 專案

上傳 Vue、Vite、Vue CLI 或 Nuxt 的靜態輸出，發佈時保留 history mode 回退、HTTPS、邊緣傳遞，以及需要時可接的自訂網域。

查看設定步驟
vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
plugins: [vue()],
// Use a deploy-safe asset base
base: './',
build: {
outDir: 'dist'
}
})
Vite 與 webpack 可用

先搞清楚要上傳哪個 Vue 資料夾

多數 Vue 部署問題在託管前就發生：上傳錯輸出資料夾、base path 錯誤，或 build 沒有先本機預覽。

Vite + Vue

npm run build
output: dist/

Vite 預設把正式建置結果放在 dist。如果 config 修改了 build.outDir 或 base，請上傳實際輸出資料夾並測試資源 URL。

Vue CLI

npm run build
output: dist/

Vue CLI 靜態 build 通常部署 dist。如果 app 會放在子路徑，publicPath 需要符合最後 URL 結構。

Nuxt static output

nuxi generate
output: .output/public or dist/

Nuxt 可以產生靜態輸出，但 server-rendered routes 和 server APIs 需要 runtime。這個流程只上傳產生後的 public 靜態檔案。

Vue Router history mode 真正需要什麼

乾淨 URL 值得保留

Hash routes 幾乎哪裡都能跑，但帶 # 的網址看起來像 workaround，分享、統計和產品質感都比較尷尬。

Vue Router history mode 讓你使用 /about 或 /dashboard/settings 這類乾淨路徑。代價是主機必須知道：不是實際檔案的路由，要回到 index.html。

DeployPages 如何處理 history mode

當請求沒有對應真實靜態資源時，DeployPages 會提供根目錄 index.html，讓 Vue Router 在瀏覽器中解析最後畫面。

  • 直接造訪巢狀路由不會立刻硬失敗。
  • 根目錄 index.html 會作為回退回應。
  • Vue mount 後讀取目前 URL，渲染正確路由。

Vue 上線前檢查

Vue app 在 dev 正常，仍可能上傳後失效。這些檢查能先抓出常見問題。

Base path

Vite 請確認 base；Vue CLI 請確認 publicPath。錯誤值通常會變成 CSS、JS、字型或圖片 404。

History 回退

直接開啟巢狀路由並重新整理。如果頁面仍正常，就表示回退設定生效。

純靜態輸出

DeployPages 提供靜態檔案。API routes、server middleware 和 SSR-only 行為需要獨立後端或 runtime。

本機預覽

請用真正的本機 preview server 檢查正式建置結果。用 file:// 開 dist/index.html 可能會隱藏或製造與部署不同的問題。

Vue 部署流程

01

建置靜態資源

在 Vite、Vue CLI 或 Nuxt static mode 執行正式建置，讓 app 產生瀏覽器可直接載入的檔案。

02

找到輸出資料夾

多數 Vue 和 Vite 專案輸出到 dist。Nuxt static 專案則依設定上傳 .output/public 或產生後的 dist。

Nuxt static build 通常依專案設定上傳 .output/public 或 dist。

03

上傳並驗證連結

上傳完整輸出資料夾，網站上線後檢查深層連結、router 導覽和資源路徑。

常見 Vue 部署問題

Fix 01

巢狀路由重新整理回 404

Vue Router 使用 history mode，但主機正在找真實檔案。使用 SPA 回退，讓未知 document route 回到 index.html。

Fix 02

CSS 或 JS 檔案回 404

檢查 Vite base 或 Vue CLI publicPath，也確認你上傳了完整 dist 資料夾，包含產生後的 assets。

Fix 03

Hash mode 可用，history mode 不行

Hash mode 把路由放在瀏覽器 # 之後。History mode 使用乾淨 URL，因此直接造訪時需要伺服器回退行為。

Fix 04

Nuxt 輸出缺少伺服器行為

Static Nuxt output 可以用檔案託管。Nuxt server routes、server middleware 和 SSR-only 行為需要 server runtime。

Vue 部署常見問題

為什麼 CSS 和 JS 檔案回 404？

這通常代表資源路徑是用另一個 base URL 建置，或 assets 目錄沒有上傳。Vite 請看 base，Vue CLI 請看 publicPath。

支援 Nuxt 嗎？

支援靜態輸出。請先產生靜態網站，再上傳生成的 public 資料夾。DeployPages 不適合 Nuxt server rendering 或 server API routes。

應該用 hash mode 還是 history mode？

想要乾淨 URL 且主機支援回退到 index.html，就用 history mode。Hash mode 較容易託管，但每個 client-side route 都會有 #。

應該上傳 Vue 原始專案嗎？

不用。請上傳正式輸出資料夾，通常是 dist。原始專案包含開發檔案和相依套件，不適合直接提供。

Pinia 或 Vuex 狀態重新整理後會保留嗎？

不會自動保留。瀏覽器重新整理會重置記憶體中的 client state。重要狀態請用 localStorage 或你偏好的 persistence plugin。

可以還原到先前版本嗎？

可以。DeployPages 保留部署歷史，需要時可以回到先前的靜態 build。