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

本篇文章同步發表於 2023 iThome 鐵人賽:Nuxt.js 3.x 筆記-打造 SSR 專案

專案開發完成後,終於到最後一步「部署」,本篇使用靜態網站生成(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

Nuxt.js 3.x Server API 整合 MongoDB 實作,邁向全端第一步 Nuxt.js 3.x Universal(SSR)專案部署到 Firebase

評論

廣告
Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×