iT邦幫忙

2023 iThome 鐵人賽

DAY 28
1
Vue.js

Nuxt.js 3.x 筆記-打造 SSR 專案系列 第 28

D28:Nuxt 3.x 將靜態網站部署到 GitHub Pages

  • 分享至 

  • xImage
  •  

本篇文章同步更新於個人部落格,歡迎交流指教~謝謝您的閱讀

專案開發完成後,終於到最後一步 「部署」,本篇將說明靜態網站生成(SSG),搭配 GitHub Pages 託管靜態網頁內容。

Static Site Generation(SSG)靜態網站生成

在編譯時產生靜態 HTML 頁面。靜態部署適合內容固定、不需資料庫、不含伺服器端動態渲染的網站(例如公司形象網站或是個人部落格),雖然不像 Universal Rendering 一樣彈性,不過靜態網站很適合搭配 CDN 緩存。


實作部署

Step1:建立 GitHub Repository

在 Github 建立一個儲存庫 <username>.github.io/<repository>連結

  • <username>:自己的使用者名稱
  • <repository>:自訂專案名,本篇範例命名為 nuxt3-generate

Step2:上傳專案至 GitHub

接著看到以下指引畫面,回到專案,依照指令上傳至 GitHub

Step3:安裝 gh-pages

專案安裝 gh-pages 套件至 devDependencies

npm i -D gh-pages

Step4:nuxt.config 配置

  • baseURL:因部署上 GitHub 網址後會加上 /<repository>/,因此須調整為 /<repository>/

    process.env.NODE_ENV 為 Node.js 環境變數,執行 npm run dev 開發模式下啟動專案,process.env.NODE_ENV 值為 "development”,在生產模式啟動專案,則為 "production"

  • buildAssetsDirassets/ 編譯後的目錄名稱,預設為 /_nuxt/,Github Pages 預設使用 Jekyll 靜態網站生成工具,Jekyll 會自動忽略所有下底線(_)前綴的資料夾與檔案,因此將 _nuxt 調整為其他名稱

// nuxt.config.js
export default defineNuxtConfig({
  app: {
    baseURL: process.env.NODE_ENV === 'production' ? '/nuxt3-generate/' : '/',
    buildAssetsDir: '/static/'
  }
}

Step5:加上 public/.nojekyll 檔案

上一步有提到,Jekyll 會自動忽略所有下底線前綴的資料夾與檔案,因此專案部署到 GitHub 後,會因 _payload.json 讀取不到,拋出 404 錯誤。在根目錄 public/ 資料夾加上 .nojekyll 空白檔案,用來告訴 GitHub 當前網站並不是基於 Jekyll 建置

Step6:加入 gh-pages 指令

package.json scripts 加入以下指令,以下指令會將編譯完成的 .output/public 靜態內容部署至 GitHub Pages

"deploy": "gh-pages --dotfiles -d .output/public"

Step7:執行部署

執行以下指令,產生靜態檔

npm run generate

編譯完成後,專案根目錄會產生一個 .output 資料夾

  • public 為靜態資源檔,定義在 public/assets/ 的檔案都會被打包在這
  • assets/ 編譯後的檔案又會被包在 static/,對應前面設定的 buildAssetsDir 目錄名稱
  • 每個靜態頁會各自編譯成 _payload.jsonindex.html
.output/
|—— public/
  |—— static/
    |—— bg.7e80f349.png
    |—— index.3fc7cdc4.js
    |—— index.9c7e60ac.css
  |—— about/
    |—— _payload.json
    |—— index.html
  |—— _payload.json
  |—— index.html
  |—— favicon.ico
  |—— ...
|—— nitro.json

接著執行部署到 GitHub Pages

npm run deploy

部署完成後,回到 GitHub 切到 gh-pages 分支,順利的話,在瀏覽器輸入網址

https://<username>.github.io/<repository>/ 就可以看到首頁畫面囉~

範例檔


加入動態路由頁面

執行 npm run generate 時,Nitro 爬蟲會先抓取靜態頁面,以及有被連結到的動態路由,沒有被連結到的動態路由必須手動配置

範例: 動態路由結構如下

pages/
|—— user/
  |—— [id].vue

nuxt.config 手動配置預渲染路由,也可以透過 ignore/ 排除路由

// nuxt.config.js
defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/user/1', '/user/2'],
      ignore: ['/dynamic']
    }
  }
});

執行 npm run generate 編譯後,在 .output 可以看到 /user/1/user/2 也預先編譯為靜態頁

.output/
|—— public/
  |—— user/
    |—— 1/
      |—— _payload.json
      |—— index.html
    |—— 2/
      |—— _payload.json
      |—— index.html
  |—— ...

延伸:自訂網域

除了使用 GitHub 提供的免費域名,也可以購買自己的網域,先前寫過一篇文章提供參考:GitHub Pages 自訂域名與 HTTPS 設定


參考資源:
https://nuxt.com/docs/getting-started/deployment
https://github.com/lucpotage/nuxt-github-pages


上一篇
D27:Nuxt 3.x 自訂 Error Page 與錯誤處理
下一篇
D29:Nuxt 3.x Universal(SSR)專案部署到 Firebase
系列文
Nuxt.js 3.x 筆記-打造 SSR 專案30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言