深入 Nuxt SSG 靜態網站生成：靈活控制每一個輸出細節

2024-08-18

Nuxt 不僅支持服務端渲染 (SSR)，還提供了靜態網站生成 (SSG) 的強大功能，讓開發者能將網站輕鬆部署到任何支援 JAMstack 的平台上。

本文將深入介紹如何利用 Nuxt 生成靜態網站，並詳細探討如何控制生成過程中的各種行為和配置選項。從預渲染設置到 assets 輸出管理，一步步展示如何靈活地掌控 Nuxt 靜態網站的生成。

生成靜態網站

在 Nuxt 中生成靜態網站非常簡單，只需要執行以下的指令即可。

Terminal

nuxt generate

控制預渲染 (Prerendering)

默認情況下，Nuxt 會在生成靜態網站時將每個頁面進行預渲染，並生成對應的 HTML 檔案。

如果你希望生成一個僅用於客戶端渲染 (Client-Side Rendering) 的 SPA 網站，可以通過在配置中將 ssr 設置為 false 來禁用預渲染功能。

nuxt.config.ts

export default defineNuxtConfig({
  ssr: false

控制輸出路徑

Nuxt 使用 Nitro 進行預渲染，並將靜態網站輸出至預設的 .output/public 目錄下。

如果需要更改輸出目錄，可以通過以下配置來控制輸出路徑：

nuxt.config.ts

export default defineNuxtConfig({
  nitro: {
    output: {
      dir: resolve('./.my-output'),
      publicDir: path.join(__dirname, './.my-output/public'),

輸出檔案目錄結構

在預渲染並生成靜態網站後，Nuxt 預設會產生以下的目錄結構。

在這個章節，我們將介紹每個檔案和目錄的用途，並探討相關配置。

📂 `_nuxt`

這個目錄包含網站的 assets 檔案，也包括所有的 CSS 和 JavaScript 文件。

你可以通過配置 app.buildAssetsDir 更改該目錄的名稱。

nuxt.config.ts

export




    
 default defineNuxtConfig({
  app: {
    buildAssetsDir: '/_my_assets/'

📂 `_nuxt/builds`

該目錄包含 App Manifest 的相關文件，這些文件提供了最新構建的 routes 及 timestamp 等。

如果你不需要這些功能，可以通過配置 experimental.appManifest 關閉此功能，從而避免生成該目錄。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    appManifest: false

📄 `_nuxt/*.js`

Nuxt 使用 Vite 的 Rollup 進行 JavaScript 打包。

你可以通過配置 vite.build 的 rollupOptions 來控制 JavaScript 文件的輸出格式，以下提供了幾個常見的配置示例：

自定義輸出檔名格式 (


                  
                  output.entryFileNames


                  
                  output.chunkFileNames

)

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: '_nuxt/my-[name]-[hash].js',
          chunkFileNames: '_nuxt/my-[name]-[hash].js'

將所有


                 
                 *.js

檔案合併為單一文件 (


                  
                  output.inlineDynamicImports

)

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          inlineDynamicImports: true

📄 `_nuxt/*.css` 和其他 assets

你可以通過配置 vite.build 來控制 CSS 和其他 assets 的輸出格式，以下提供了一些設定範例：

自定義輸出檔名格式 ( rollupOptions.output.assetFileNames )

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          assetFileNames: '_nuxt/my-[name]-[hash].[ext]',
          // or
          assetFileNames: (assetInfo) => {
            if (assetInfo?.name?.endsWith('.css'))
              return '_nuxt/style-[name]-[hash].css'
            return '_nuxt/[name]-[hash].[ext]'

這個設置將影響所有 assets，包括圖片、字體等。

將所有 *.css 檔案合併為單一文件 ( cssCodeSplit )

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    build: {
      cssCodeSplit: false

對於存放在 assets/ 目錄下的其他檔案（如圖片、字型等），它們可能會被複製到 _nuxt 目錄中。

如果你希望強制將所有資產文件內嵌（inline），而不是複製到 _nuxt 目錄，你可以使用以下配置來實現：

nuxt.config.ts

export




    
 default defineNuxtConfig({
  vite: {
    build: {
      assetsInlineLimit: Number.MAX_SAFE_INTEGER

📄 `_payload.json`

該文件在 SSR 或預渲染過程中用來傳遞頁面的 payload 資料。

如果你不需要外部載入該文件，並希望在生成靜態網站時不生成此文件，可以通過配置 payloadExtraction 來禁用它。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: false

📄 `200.html` 和 `404.html`

這兩個文件在 SSG 時生成，作為 SPA 網站的 fallback 頁面。

如果你不需要這些文件，可以通過配置 nitro.prerender.ignore 來避免生成。

nuxt.config.ts

export default defineNuxtConfig({
  nitro: {
    prerender: {
      ignore: ['/200.html', '/404.html']

📄 `index.html`

Nuxt 會為你網站的每個頁面都生成對應的 index.html 文件，作為靜態網站的入口。

Preload 與 Prefetch

這些 Resource Hints 可以幫助瀏覽器提前加載資源，從而加快網站加載速度。

index.html

<!DOCTYPE html>
<html data-capo="">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="fetch" crossorigin="anonymous" href="/_payload.json?93d23bea-82a5-406d-92a4-feb73d5bf1b8">
    <link rel="modulepreload" as="script" crossorigin href="/_nuxt/D9xaLgge.js">
    <link rel="prefetch" as="script" crossorigin href="/_nuxt/BXlAlM0q.js">
    <link rel="prefetch" as="script" crossorigin href="/_nuxt/BRJtm5m-.js">
    <link rel="prefetch" as="script" crossorigin href="/_nuxt/CZvqSstT.js">
    <script type="module" src="/_nuxt/D9xaLgge.js" crossorigin></script>
  </head>
  </body>
</html>

如果需要禁用 preload 和 prefetch ，可以使用 Nuxt Hooks 的 build:manifest 進行自定義，以下示範了如何禁用這些功能：

nuxt.config.ts

export default defineNuxtConfig({
  hooks: {
    'build:manifest': (manifest) => {
      console.log('manifest', manifest)
      for (const key in manifest) {
        manifest[key].dynamicImports = []
        manifest[key].prefetch = false
        manifest[key].preload = false