# 如何在 GitHub Pages 設定自訂域名並啟用免費的 TLS 憑證

我最近都在準備 [實戰 E2E 測試：使用 Playwright 測試框架](https://www.accupass.com/go/e2e-playwright) 課程，也為這堂課特別精心翻譯了整個 [playwright.dev](https://playwright.dev/) 網站，甚至還買了一個 [playwright.tw](https://playwright.tw/) 域名，並把翻譯好的網站部署到 GitHub Pages 上面。[GitHub Pages](https://pages.github.com/) 是 GitHub 提供的免費靜態網頁服務，使用者可以透過 GitHub Pages 建立個人網站、部落格、文件網站等。今天這篇文章我將介紹如何在 GitHub Pages 設定自訂域名與啟用免費的 TLS 憑證。

![the process of setting up a custom domain and enabling free TLS certificates on GitHub Pages](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/c89d96ff2fcff5a294ca-6f721bce-0f3c-456c-a1b8-c2b8aa7b48b3.webp)

> 注意: 本文不打算介紹完整的 GitHub Pages 完整用法，怎樣部署不在本篇文章範圍。

這篇文章我就打算做到兩件事：

1.  設定**自訂域名**
    
    在 GitHub Pages 設定**自訂域名**很簡單，設定好 `CNAME` 檔案之後，再到 DNS 伺服器上加上一個 `CNAME` 記錄，將域名驗證過就可以使用了。
    
    但若要設定 **根域名** (Apex Domain) 的話，就不能設定 `CNAME` 記錄，而是一定要設定 `A` 與 `AAAA` 記錄。
    
    > `Apex Domain` (根域名) 是一個不包含「子域名」的自訂域名，例如 `playwright.tw` 就屬於一種 `Apex Domain`，他是屬於頂層域名(Top-Level Domain) `.com` 轄下的子域名，一般公司可以申請與的 Domain 都是這種。如果替你的 Domain 加上的 `www` 子域名，那就不能稱為 `Apex Domain` 了。
    
2.  設定免費的 TLS 憑證
    
    在 GitHub Pages 申請免費的 TLS 憑證是全自動的，強制使用 HTTPS 連線也很簡單，一個勾選就完成了。
    
    > [GitHub Pages](https://pages.github.com/) 已經自動與 [Let's Encrypt](https://letsencrypt.org/) 整合，能夠自動為你的自訂域名申請並管理 SSL 憑證，這樣你的網站就可以安全地透過 HTTPS 訪問。
    

這裡所謂的 `Apex Domain` 其實有很多種不同的別名，但都代表一樣的意思，例如 `Base Domain` (基礎域名), `Bare Domain` (裸域名), `Naked Domain` (裸域名), `Root Apex Domain` (根域名), `Zone Apex Domain` (區域根域名) 等等。至於在中文翻譯部分，Domain 有些人稱「域名」，但有些人會說「網域」，其實只是翻譯不同，在 DNS 的領域中，意思是一樣的。詳見 [DNS (Domain Name Service) | Complete Think](https://rickhw.github.io/2016/03/14/ComputerScience/DNS/)。

我個人口語上會說 `Apex Domain` 是「根域名」，而不會說「頂級域名」或「頂層域名」，因為這會跟 `Top-Level Domain` (TLD) 搞混，其實 TLD 是像 `.com`, `.org`, `.net` 這樣的域名，這部分翻譯成「頂層域名」會比較恰當。

### 設定自訂域名的流程

GitHub Pages 套用自訂域名的流程大致如下：

1.  你要先有一個 GitHub Repo
    
    例如：
    
    ```
    https://github.com/doggy8088/playwright.tw
    ```
    
2.  到 [GitHub Repo > Settings > Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) 加入一個自訂域名驗證
    
    這個步驟要先輸入你要驗證的自訂域名網址：
    
    ![Repo > Settings > Pages: playwright.tw](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/fb9e502517c970c8eb42-6c879bd0-453e-43f5-bb9e-77211882c09b.jpg)
    
    然後 GitHub 會告訴你要在 DNS 伺服器上加入一個 `TXT` 紀錄，這個紀錄是 GitHub 提供的驗證碼：
    
    ![Repo > Settings > Pages: playwright.tw > Add a DNS TXT record](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/092e95ce39fa3172a165-201896a1-5d02-41b3-962a-eb5ea5e785c7.jpg)
    
    你到 DNS 伺服器加入 TXT 記錄後，按下 `Verify` 按鈕就可以進行驗證，驗證成功後的畫面如下：
    
    ![Repo > Settings > Pages: playwright.tw 驗證成功](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/ce3bccc3c8d56f5d0f92-db245e22-57bf-46d8-9fc4-715f8892fde2.jpg)
    
    > 驗證域名的文件: [Verifying your custom domain for GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages)
    
3.  接著要設定 `Apex Domain` 的 `A` (IPv4) 與 `AAAA` (IPv6) 記錄
    
    若要建立 `www.playwright.tw` 之類的自訂域名，你只要在 DNS 伺服器加入 `CNAME` 記錄並指向 `[username].github.io` 域名即可。
    
    但是若要設定 `Apex Domain` 的自訂域名，例如 `playwright.tw` 這樣的根域名，你就必須在 DNS 伺服器上設定 `A` 與 `AAAA` 記錄，這兩個記錄是指向 GitHub Pages 的伺服器 IP 位址。
    
    GitHub Pages 要求 `A` 記錄要設定以下四筆：
    
    ```
    185.199.108.153
    185.199.109.153
    185.199.110.153
    185.199.111.153
    ```
    
    GitHub Pages 要求 `AAAA` 記錄要設定以下四筆：
    
    ```
    2606:50c0:8000::153
    2606:50c0:8001::153
    2606:50c0:8002::153
    2606:50c0:8003::153
    ```
    
    > 設定自訂域名的文件: [Managing a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site)
    
4.  除了設定 `Apex Domain` 之外，GitHub 也建議你一併設定好 `www` 子網域
    
    假設你的 `Apex Domain` 是 `playwright.tw` 的話，你只要在 DNS 伺服器加入名為 `www.playwright.tw` 的 `CNAME` 記錄並指向 `[username].github.io` 域名即可。
    
    設定好之後，無論使用者是輸入 `playwright.tw` 或是 `www.playwright.tw` 都會被導向到你的 GitHub Pages 網站。
    
5.  最後在 Repo 的根目錄下建立一個名為 `CNAME` 的檔案，內容為自訂域名，推送到 Repo 之後，自訂域名就會自動生效了！
    
    ```
    playwright.tw
    ```
    

### 啟用免費的 TLS 憑證

基本上，你的自訂域名只要都如實的設定好，GitHub Pages 就會自動幫你申請免費的 TLS 憑證，這樣你的網站就可以透過 HTTPS 連線了。

只是，若你想要強制使用者永遠透過 HTTPS 連線，你只要到 `GitHub Repo > Settings > Pages` 勾選 `Enforce HTTPS` 選項即可：

![Enforce HTTPS](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/ca094bc19c493b3bff82-63b34a8e-2565-4c88-bef7-dddf0a07f9a3.jpg)

### 相關連結

-   [GitHub Pages](https://pages.github.com/)
-   [GitHub Pages Custom Domains](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site)
-   [Verifying your custom domain for GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages)
-   [DNS (Domain Name Service) | Complete Think](https://rickhw.github.io/2016/03/14/ComputerScience/DNS/)