Astro 5 + Vue 3 SSR 完整設定指南 | EZ Tech Blog

前言

Astro 5 帶來了全新的 Content Layer API 與 Server Islands，讓我們能用更彈性的方式整合 Vue 3 元件。本文將帶你從零開始完成一個生產可用的 SSR 專案。

環境需求

Node.js 18+
pnpm / npm / yarn

安裝與初始化

npm create astro@latest my-app -- --template basics
cd my-app
npx astro add vue
npx astro add tailwind

astro.config.mjs 設定

import { defineConfig } from "astro/config";
import vue from "@astrojs/vue";
import tailwind from "@astrojs/tailwind";

export default defineConfig({
  integrations: [vue(), tailwind()],
  output: "server",
});

設定 output: "server" 後，所有頁面預設走 SSR，靜態資源仍由 Astro 優化打包。

Islands Architecture 最佳實踐

Astro 的核心優勢在於 Islands Architecture：大部分頁面靜態渲染，只在需要互動的元件上掛載 Vue。

---
// 靜態部分由 Astro 渲染
import MyInteractiveWidget from "../components/MyInteractiveWidget.vue";
---

<section>
  <h1>靜態標題，零 JavaScript</h1>
  <!-- 只有這個元件會水合 Vue runtime -->
  <MyInteractiveWidget client:load />
</section>

client 指令選擇

指令	時機
`client:load`	頁面載入後立即水合
`client:idle`	主執行緒空閒後才水合
`client:visible`	元件進入 viewport 才水合
`client:only="vue"`	完全跳過 SSR，純客戶端渲染

常見陷阱

window / document 在 SSR 時不存在 — 將存取包在 onMounted() 或 import.meta.env.SSR 判斷裡。
Vue <Transition> 水合不匹配 — 確保 SSR 與 CSR 渲染的 DOM 結構一致。
動態 import() 路徑 — Astro SSR 模式下需注意動態 import 的 chunk splitting 行為。

結語

Astro + Vue 的組合在效能與開發體驗間取得了良好平衡。只要理解 Islands 的邊界在哪裡，就能寫出快速且可維護的現代網站。

前言