2023/10/03
# Vite 部署靜態網頁 Github Pages 含 Vue Router 設置

## 使用工具和前置作業
- Vite
- pnpm
- 已經建立好的 GitHub Repository 遠端庫

## 修改vite.config.ts
根據官方文件說明，若預期部署在https://<USERNAME>.github.io/<REPONAME>/ 網址上，首先需要在本地專案中的`vite.config.ts`新增或修改base屬性。
例如我的遠端庫名稱`<REPONAME>`為`vue-weather-app`，那麼就設定`base` 為`'/vue-weather-app/'`:

export default defineConfig({
  plugins: [vue()],
  base: '/vue-weather-app/',
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
});

*需要合乎命名規則，並注意名稱務必一致。

## 專案項目打包，生成dist目錄
根據`package.json`的腳本內容用vite打包專案，以命令列執行`pnpm build`。
執行後會在專案根目錄生成dist目錄內含打包後的`index.html`等文件，也就是接下來實際部署的程式碼來源。
之後若想先預覽本地環境靜態網頁的建構，我們可以在命令列執行`pnpm preview`。

## 修改`.gitignore`文件，準備將dist目錄推送至遠端庫
畢竟網頁是部署在遠端，勢必得推送上傳dist目錄。
在推送之前記得將`.gitignore`文件內設定的dist參數刪除或註解才能上傳。

## 將dist目錄推送到遠端庫的gh-pages分支
為了將主要開發文件和部署靜態網頁文件區隔開來，並且方便之後管理，我們在本地命命列執行以下程式碼，將`dist`內含的文件推送到新建的gh-pages分支
>git subtree push --prefix dist origin gh-pages


## 在 GitHub 遠端庫的設定中，啟用 GitHub Pages

順利上傳靜態網頁文件後，前往 GitHub Repository>Settings>Pages

1. Source 來源選擇 Deploy from a branch
2. Branch 選擇 gh-pages分支的根目錄/(root)


選好之後按Save儲存，回到專案主頁，看到顯示綠色圓點的github-pages代表成功完成布署:


可以回到之前的Settings>Pages瀏覽部署好的網址:


## 小結
目前為止我們所做的就是指定gh-pages分支作為部署網頁的來源以正式啟用GitHub Pages。

關於GitHub Pages建構及部署來源(發布來源)的設置，有兩個模式可以選擇:
- 在將程式碼推送到特定分支時部署網頁(這次部署採用方式)。
- 編寫 GitHub Actions 工作流程(Workflow)來部署網頁，

我會在下一篇文章示範 Workflow 腳本以使用 GitHub Actions 實施自動化部署。

# 遇到的問題
## 如何取消部署GitHub Pages?
一開始我用main主分支測試部署功能，但是我想改用gh-pages做為新的部署分支，當作唯一github pages部署來源，要如何移除原先main分支來源部署的github pages呢?或者我想改用Netlify或Vercel來部署我的網頁，而不想使用GitHub Pages，該如何取消/移除既有GitHub Pages部署網頁?

GitHub遠端庫主頁和設定都找不到明確取消GitHub Pages部署的選項，官方文件的介紹已過時，後來找到這個討論串:
https://github.com/orgs/community/discussions/22018

最簡單移除GitHub Pages的方法是:
刪除專案遠端庫Setting的Environments設定。刪除後便會取消GitHub Pages的線上部署網頁，之後便可以依照需求重新部署。

## Vue Router 設定 Hash / HTML5 History 模式
vue-router 讓我們可以根據偏好或網頁需求使用`createWebHashHistory`或是`createWebHistory`。
兩者在網址外觀上的差異:

https://example.com/#/           //Hash 
https://example.com/#/about   //Hash
https://example.com/             //HTML5
https://example.com/about     //HTML5

### Hash mode
- 使用`createWebHashHistory`。
- 是vue-router預設的模式，如果沒有設定就會是hash mode，會在網址後加上一個`#`。
- 簡單來說很像瀏覽器的錨點功能，`#`號後的URL變化不會向伺服器發送請求，不需要後端相對應的配置。

import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    //...
  ],
})

### HTML5 mode
- 使用`createWebhHistory`。
- 官方推薦模式，因為網址省略`#`，會使網址看起來很"正常"。
- URL的變化都會向伺服器發送一個請求。
- 如果有設置除首頁外多個路由網址，後端需要相應的配置，否則若使用者端直接訪問其他路由網址，會導至404 error頁面。
- 例如使用者在瀏覽器直接訪問`https://example.com/about`，在前端只有設置根目錄一份index.html的前提下，伺服器要依據請求找尋根目錄下的about目錄下的index.html文件，但根本就沒有這個about目錄，因此返回404 error頁面了。
- 一個簡單的後端配置是在根目錄創建一個404.html文件，內容和index.html文件相同。

import { createRouter, createWebhHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    //...
  ],
})

## 參考
- Vite 部署靜態網頁官方文件 https://cn.vitejs.dev/guide/static-deploy.html
- Vue Router官方文件設定 https://router.vuejs.org/zh/guide/essentials/history-mode.html
- https://juejin.cn/post/7228851979463032890
- https://juejin.cn/post/7264783369878388796
- https://jerry-yeh.github.io/vue-3/20210911/13819/