設定 SSR | Quasar Framework

Quasar CLI 搭配 Webpack - @quasar/app-webpack

設定 SSR

quasar.config 檔案

您可以在此處設定一些 SSR 選項。例如，如果您希望客戶端以 SPA（單頁應用程式 – 預設行為）或 PWA（漸進式網頁應用程式）接管。

return {
  // ...
  ssr: {
    pwa: true/false, // should a PWA take over (default: false), or just a SPA?

    /**
     * Manually serialize the store state and provide it yourself
     * as window.__INITIAL_STATE__ to the client-side (through a <script> tag)
     * (Requires @quasar/app-webpack v3.5+)
     */
    manualStoreSerialization: false,

    /**
     * Manually inject the store state into ssrContext.state
     * (Requires @quasar/app-webpack v3.5+)
     */
    manualStoreSsrContextInjection: false,

    /**
     * Manually handle the store hydration instead of letting Quasar CLI do it.
     * For Pinia: store.state.value = window.__INITIAL_STATE__
     * For Vuex: store.replaceState(window.__INITIAL_STATE__)
     */
    manualStoreHydration: false,

    /**
     * Manually call $q.onSSRHydrated() instead of letting Quasar CLI do it.
     * This announces that client-side code should takeover.
     */
    manualPostHydrationTrigger: false,

    prodPort: 3000, // The default port that the production server should use
                    // (gets superseded if process∙env∙PORT is specified at runtime)

    maxAge: 1000 * 60 * 60 * 24 * 30,
        // Tell browser when a file from the server should expire from cache
        // (the default value, in ms)
        // Has effect only when server.static() is used

    // List of SSR middleware files (src-ssr/middlewares/*). Order is important.
    middlewares: [
      // ...
      'render' // Should not be missing, and should be last in the list.
    ],

    // optional; add/remove/change properties
    // of production generated package.json
    extendPackageJson (pkg) {
      // directly change props of pkg;
      // no need to return anything
    },

    // optional;
    // handles the Webserver webpack config ONLY
    // which includes the SSR middleware
    extendWebpackWebserver (cfg) {
      // directly change props of cfg;
      // no need to return anything
    },

    // optional; EQUIVALENT to extendWebpack() but uses webpack-chain;
    // handles the Webserver webpack config ONLY
    // which includes the SSR middleware
    chainWebpackWebserver (chain) {
      // chain is a webpack-chain instance
      // of the Webpack configuration
    }
  }
}

如果您決定使用 PWA 客戶端接管（這是一個絕佳的組合），也會安裝 Quasar CLI PWA 模式。您可能需要查看 Quasar PWA 指南。但最重要的是，請務必閱讀 SSR 與 PWA 頁面。

在建置時，extendWebpack() 和 chainWebpack() 將會收到一個額外的參數 (Object)，目前包含 isServer 或 isClient 布林屬性，因為將會有兩個 Webpack 建置（一個用於伺服器端，另一個用於客戶端）。

build: {
  extendWebpack(cfg, { isServer, isClient }) { ... }
}

如果您想要更多資訊，請參閱此頁面，其中詳細介紹了 /quasar.config 檔案中的處理 webpack。

手動觸發 store hydration

預設情況下，Quasar CLI 會負責在客戶端上 hydration Vuex store（如果您使用的話）。

但是，如果您希望自行手動 hydration，則需要設定 quasar.config file > ssr > manualStoreHydration: true。一個很好的例子是從啟動檔案執行

// MAKE SURE TO CONFIGURE THIS BOOT FILE
// TO RUN ONLY ON CLIENT-SIDE

export default ({ store }) => {
  // For Pinia
  store.state.value = window.__INITIAL_STATE__

  // For Vuex
  store.replaceState(window.__INITIAL_STATE__)
}

手動觸發 post-hydration

預設情況下，當此包裝器元件被掛載時，Quasar CLI 會包裝您的 App 元件，並在客戶端上呼叫 $q.onSSRHydrated()。這是客戶端接管的時刻。您不需要為此設定任何內容。

但是，如果您希望覆寫此事件發生的時刻，則需要設定 quasar.config file > ssr > manualPostHydrationTrigger: true。無論您的原因是什麼（非常客製化的用例），這是一個手動觸發 post hydration 的範例

Composition API

Options API

// App.vue

import { onMounted } from 'vue'
import { useQuasar } from 'quasar'
export default {
  // ....
  setup () {
    // ...
    const $q = useQuasar()
    onMounted(() => {
      $q.onSSRHydrated()
    })
  }
}

Nodejs 伺服器

將 SSR 模式新增至 Quasar 專案意味著將會建立一個新資料夾：/src-ssr，其中包含 SSR 特定檔案

src-ssr/

middlewares/

# SSR 中介軟體檔案

directives/

# Vue 指令的 SSR 轉換

production-export.js

# SSR 網頁伺服器生產匯出

您可以自由編輯這些檔案。這兩個資料夾中的每一個都在其自己的文件頁面中詳細說明（查看左側選單）。

請注意幾件事

如果您從 node_modules 匯入任何內容，請確保該套件已在 package.json > “dependencies” 中指定，而不是在 “devDependencies” 中。
/src-ssr/middlewares 是透過單獨的 Webpack 設定建置的。當 Quasar App CLI 建置您的應用程式時，您會看到它標記為「Webserver」。 您可以透過 /quasar.config 檔案鏈式/擴展這些檔案的 Webpack 設定

return {
  // ...
  ssr: {
    // ...

    // optional; webpack config Object for
    // the Webserver part ONLY (/src-ssr/)
    // which is invoked for production (NOT for dev)
    extendWebpackWebserver (cfg) {
      // directly change props of cfg;
      // no need to return anything
    },

    // optional; EQUIVALENT to extendWebpack() but uses webpack-chain;
    // the Webserver part ONLY (/src-ssr/)
    // which is invoked for production (NOT for dev)
    chainWebpackWebserver (chain) {
      // chain is a webpack-chain instance
      // of the Webpack configuration
    }
  }
}

/src-ssr/production-export.js 檔案在 SSR 生產匯出頁面中詳細說明。如果您需要支援無伺服器函數，請特別閱讀它。

協助 SEO

當您開發 SSR 而不是 SPA 時，主要原因之一是為了照顧 SEO。而且透過使用 Quasar Meta 外掛程式來管理搜尋引擎所需的動態 html 標記，可以大大改善 SEO。

啟動檔案

在 SSR 模式下執行時，您的應用程式程式碼需要是同構或「通用」的，這表示它必須同時在 Node 環境和瀏覽器中執行。這也適用於您的啟動檔案。

但是，在某些情況下，您可能只希望某些啟動檔案僅在伺服器端或僅在客戶端執行。您可以透過指定來實現這一點

return {
  // ...
  boot: [
    'some-boot-file', // runs on both server and client
    { path: 'some-other', server: false }, // this boot file gets embedded only on client-side
    { path: 'third', client: false } // this boot file gets embedded only on server-side
  ]
}

不過，請確保您的應用程式是一致的。

當啟動檔案在伺服器上執行時，您將可以在預設匯出的函數上存取一個額外的參數（稱為 ssrContext）

export default ({ app, ..., ssrContext }) => {
  // You can add props to the ssrContext then use them in the src/index.template.html.
  // Example - let's say we ssrContext.someProp = 'some value', then in index template we can reference it:
  // {{ someProp }}
}

當您將此類參考（範例上方括號括住的 someProp）新增到您的 /index.html 或 /src/index.template.html 中時，請確保您告訴 Quasar 它僅對 SSR 建置有效

<% if (ctx.mode.ssr) { %>{{ someProp }} <% } %>

發現錯誤？在瀏覽器中編輯此頁面

1. 簡介

2. quasar.config 檔案

2.1. 手動觸發 store hydration

2.2. 手動觸發 post-hydration

3. Nodejs 伺服器

4. 協助 SEO

5. 啟動檔案