部署

若要建立供實際使用之靜態網站檔案，請執行

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

完成後靜態檔案將會產生在 build 目錄中。

注意

Docusaurus 唯一的責任是建構你的網站並在 build 中發射靜態檔案。

現在你可以選擇如何主機這些靜態檔案了。

您可以將您的網站部署到以下靜態網站託管服務：Vercel、GitHub Pages、Netlify、Render 以及 Surge。

將 Docusaurus 網站靜態地呈現，且它通常可以在沒有 JavaScript 的情況下運作！

配置

在 docusaurus.config.js 中需要下列參數才能最佳化路由並從正確的位置提供檔案

名稱	說明
網址	您網站的網址。如果網站部署在 https://my-org.com/my-project/，那 url 就是 https://my-org.com/。
基礎網址	專案的基礎網址，加上結尾的斜線。如果網站部署在 https://my-org.com/my-project/，那 baseUrl 就是 /my-project/。

在本地測試您的組建

在部署供生產使用之前，在本地測試您的組建非常重要。Docusaurus 提供了 docusaurus serve 指令

npm

npm run serve

Yarn

yarn serve

pnpm

pnpm run serve

預設值是將您的網站載入 https://127.0.0.1:3000/。

尾部斜線配置

Docusaurus 有個 trailingSlash 配置，用於自訂網址/連結和發出的檔名格式。

預設值通常都能正常運作。很不幸的是，每個靜態託管供應商都有不同的行為，而且將完全相同的網站部署到不同的主機可能會造成不同的結果。根據您的主機，變更這個配置可能會很有用。

提示

使用 slorber/trailing-slash-guide 更深入了解您的主機行為，並適當地配置 trailingSlash。

使用環境變數

將可能具有敏感性的資訊放入環境是常見的做法。然而，在典型的 Docusaurus 網站中，docusaurus.config.js 檔案是與 Node.js 環境的唯一介面（請參閱 我們的架構概覽），而其他所有部分（MDX 頁面、React 元件等）都是客戶端且無法直接存取 process 全域變數。在此情況下，您可以考慮使用 customFields 來將環境變數傳遞到客戶端。

docusaurus.config.js

// If you are using dotenv (https://www.npmjs.com/package/dotenv)
import 'dotenv/config';

export default {
  title: '...',
  url: process.env.URL, // You can use environment variables to control site specifics as well
  customFields: {
    // Put your custom environment here
    teamEmail: process.env.EMAIL,
  },
};

home.jsx

import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function Home() {
  const {
    siteConfig: {customFields},
  } = useDocusaurusContext();
  return <div>Contact us through {customFields.teamEmail}!</div>;
}

選擇一個主機供應商

有幾個常見的主機選項

• 自行主機和 Apache2 或 Nginx 等 HTTP 伺服器。
• Jamstack 供應商（例如 Netlify 和 Vercel）。我們將使用它們作為參考，但相同的理由也可以套用於其他供應商。
• GitHub Pages（根據定義，它也是 Jamstack，但我們會分別比較）。

如果您不確定要選擇哪一個，請詢問以下問題

我在這方面願意投入多少資源（金錢、人時數等）？

• 🔴 自行主機需要網路、Linux 和網路伺服器管理方面的經驗。這是最困難的選項，而且需要花費最多時間才能成功管理。在費用方面，雲端服務幾乎從不免費，而購買/配置現場伺服器甚至會更昂貴。
• 🟢 Jamstack 供應商可以幫助您在幾乎沒有時間的情況下建立一個可運作的網站，並提供一些功能，例如易於配置的伺服器端重新導向。許多供應商都為免費方案提供豐厚的建置時間配額，您幾乎永遠不會超過此配額。但是，免費方案有其限制，一旦達到這些限制，您就需要付費。請查看供應商的價格頁面以了解詳情。
• 🟡 GitHub Pages 配置工作流程可能會很繁瑣。（證據：請參閱 配置到 GitHub Pages的長度！）然而，此服務（包括建 置和配置）對於公用儲存庫來說永遠是免費的，並且我們有詳細的說明以協助您順利操作。

我需要多少伺服器端自訂功能？

• 🟢 自行主機讓我們可以使用整個伺服器的配置。您可以根據要求 URL 配置虛擬主機來提供不同的內容，您可以進行複雜的伺服器端重新導向，您可以實作驗證等。如果您需要許多伺服器端功能，請自行主機您的網站。
• 🟡 Jamstack 通常提供一些伺服器端配置（例如 URL 格式化（尾部斜線）、伺服器端重新導向等）。
• 🔴 GitHub Pages 除了強制使用 HTTPS 和設定 CNAME 記錄之外，並未公開伺服器端配置。

我需要有利於協作的配置工作流程嗎？

• 🟡 自我託管服務可以利用連續部署功能，像是 Netlify，但會涉及更繁重的任務。一般而言，你會指定一個特定的人來管理部署，而且工作流程不會像其餘兩個選項那樣以 git 為基礎。
• 🟢 Netlify 和 Vercel 對每個 pull request 都會預覽部署，對於團隊在併入到生產之前檢閱工作很有幫助。你也可以管理具有不同成員訪問權限的團隊，以進行部署。
• 🟡 GitHub Pages 無法以非混雜的方式進行預覽部署。1 個 repo 只可以關聯到 1 個網站部署。另一方面，你可以控制誰有權限寫入網站部署。

沒有萬靈丹。在做選擇之前，你需要仔細衡量你的需求和資源。

自我託管

Docusaurus 可以使用 docusaurus serve 以自我託管的方式進行。請使用 --port 變更連接埠，並使用 --host 變更主機。

npm

npm run serve -- --build --port 80 --host 0.0.0.0

Yarn

yarn serve --build --port 80 --host 0.0.0.0

pnpm

pnpm run serve --build --port 80 --host 0.0.0.0

警告

與靜態託管提供程式 / CDN 相比，這並非最佳的選項。

警告

在以下各節中，我們將介紹幾個常見的託管提供程式，以及它們應如何設定才能最有效率地部署 Docusaurus 網站。Docusaurus 沒有與任何這些服務聯盟，而且這些資訊僅供參考。部分說明是由第三方提供，最新的 API 變更可能未反映在我們這邊。如果你看到過時的內容，歡迎提供 PR。

由於我們只能盡力提供這些內容，因此我們已停止接受加入新託管選項的 PR。不過，你可以在其他網站（例如你的部落格，或提供程式的官方網站）發佈說明，並要求我們將連結加入你的說明。

在 Netlify 中部署

要將 Docusaurus 網站部署到 Netlify，請先確定已正確設定下列選項

docusaurus.config.js

export default {
  url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
  baseUrl: '/', // Base directory of your site relative to your repo
  // ...
};

接著，使用 Netlify 建立網站。

設定網站時，請設定下列建置指令和目錄

• 建置指令：npm run build
• 發佈目錄：build

如果你沒有設定這些建置選項，你仍然可以在網站建立後前往「網站設定」->「建置與部署」。

完成上述選項的設定後，你的網站將會部署，並在併入到部署分支（預設為 main）後自動重新部署。

警告

有些 Docusaurus 網站會將 docs 資料夾放在 website 資料夾外 (這很可能是以前的 Docusaurus v1 網站)

repo           # git root
├── docs       # MD files
└── website    # Docusaurus root

如果您決定將 website 資料夾用為 Netlify 的基本目錄，當您更新 docs 資料夾時，Netlify 將不會觸發建置，而且您需要設定一個 自訂的 ignore 指令

website/netlify.toml

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"

警告

預設情況下，Netlify 會將尾斜線加到 Docusaurus URL。

建議停用 Netlify 設定 後處理 > 資產最佳化 > 美化 URL，以避免出現小寫的 URL、不必要的重新導向和 404 錯誤。

請特別小心：停用資產最佳化 全域核取方塊損壞，實際上並未停用 美化 URL 設定。請務必獨立取消它的核取。

如果您要保留 美化 URL Netlify 設定，請適當地調整 trailingSlash Docusaurus 設定。

請參閱 slorber/trailing-slash-guide 以取得更多資訊。

部署到 Vercel

將您的 Docusaurus 專案部署到 Vercel，會在效能和易用性方面為您提供 各種好處。

要利用 Vercel for Git 的整合 來部署您的 Docusarus 專案，請確定已將其推送到 Git 存放庫。

使用 匯入流程 將專案匯入 Vercel。在匯入期間，您會發現所有相關的選項都已為您預先設定，不過您可以選擇變更這些 選項。

在專案匯入後，所有後續推送到分支都會產生 預覽部署，而且對 製作分支 (通常是「main」或「master」) 所做的所有變更都會導致 製作部署。

部署到 GitHub Pages

Docusaurus 提供一個簡單的方法，讓您可以發佈到 GitHub Pages，它附贈在每一個 GitHub 存放庫中。

概觀

通常，發佈過程涉及兩個儲存庫（至少兩個分支）：包含來源檔的分支，以及包含要使用 GitHub Pages 提供的建置輸出的分支。在以下教學課程中，它們分別稱為「來源」和「部署」。

每個 GitHub 儲存庫都與 GitHub Pages 服務相關聯。如果部署儲存庫稱為 my-org/my-project（其中 my-org 是組織名稱或使用者名稱），已部署的網站將顯示在 https://my-org.github.io/my-project/。如果部署儲存庫稱為 my-org/my-org.github.io (組織 GitHub Pages 儲存庫)，該網站將顯示在 https://my-org.github.io/。

資訊

如果您想為 GitHub Pages 使用自訂網域，請在 static 目錄中建立 CNAME 檔案。static 目錄中的所有內容都將複製到 build 目錄的根目錄，以供部署。使用自訂網域時，您應該能夠從 baseUrl: '/projectName/' 退回至 baseUrl: '/'，還可以將 url 設定為您的自訂網域。

您可以參閱 GitHub Pages 的文件 使用者、組織和專案頁面，以取得更多詳細資料。

GitHub Pages 從預設分支（通常為 master / main）或 gh-pages 分支，以及從根目錄或 /docs 資料夾提取已準備就緒的部署檔案（docusaurus build 的輸出）。您可以透過您的儲存庫中的 Settings > Pages 來設定。此分支將稱為「部署分支」。

我們提供 docusaurus deploy 指令，可協助您使用單一指令將您的網站從來源分支部署到部署分支：複製、建置和提交。

docusaurus.config.js 設定

首先，修改您的 docusaurus.config.js 並加入下列參數

名稱	說明
organizationName	擁有部署儲存庫的 GitHub 使用者或組織。
projectName	部署儲存庫的名稱。
deploymentBranch	部署分支的名稱。它預設為 'gh-pages'（針對非組織的 GitHub Pages 儲存庫（projectName 未以 .github.io 結尾））。否則，在組態欄位或環境變數中，必須明確指出該組態。

這些欄位也有其環境變數對應項，且優先權較高：ORGANIZATION_NAME、PROJECT_NAME 和 DEPLOYMENT_BRANCH。

警告

GitHub Pages 預設會在 Docusaurus URL 加入斜線結尾。建議設定 trailingSlash 組態（true 或 false，不是 undefined）。

範例

docusaurus.config.js

export default {
  // ...
  url: 'https://endiliey.github.io', // Your website URL
  baseUrl: '/',
  projectName: 'endiliey.github.io',
  organizationName: 'endiliey',
  trailingSlash: false,
  // ...
};

警告

在預設值下，GitHub Pages 會執行發布檔案透過 Jekyll 的方式運行。由於 Jekyll 會捨棄任何以 _ 開頭的檔案，因此建議您在 static 目錄中新增一個名為 .nojekyll 的空檔案，以停用 Jekyll。

環境設定值

名稱	說明
USE_SSH	設定為 true 可使用 SSH 取代預設 HTTPS 連線 GitHub repo。如果原始 repo URL 是 SSH URL（例如：[email protected]:facebook/docusaurus.git），會推論出 USE_SSH 為 true。
GIT_USER	具有 GitHub 帳戶的使用者名稱，這個帳戶擁有推播權限以供應檔案部署。對於您自己的儲存庫，這通常會是您的 GitHub 使用者名稱。若不使用 SSH，此設定為必要的；否則，將會忽略此設定。
GIT_PASS	Git 使用者的個人存取權杖（由 GIT_USER 指定），以便進行非互動式部署（例如，連續部署）
CURRENT_BRANCH	來源分支。通常，分支會是 main 或 master，但它可以是以 gh-pages 為例外的任何分支。若沒有設定此變數，則會使用叫用 docusaurus deploy 的目前分支。
GIT_USER_NAME	推播到部署 repo 時要用到的 git config user.name 值
GIT_USER_EMAIL	推播到部署 repo 時要用到的 git config user.email 值

GitHub enterprise 安裝應與 github.com 以相同的方式運作；您只需要將組織的 GitHub Enterprise 主機設定為環境變數

名稱	說明
GITHUB_HOST	您的 GitHub enterprise 網站的網域名稱。
GITHUB_PORT	您的 GitHub enterprise 網站的埠號。

部署

最後，若要部署您的網站到 GitHub Pages，請執行

Bash

GIT_USER=<GITHUB_USERNAME> yarn deploy

Windows

cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

PowerShell

cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

警告

從2021年8月開始，GitHub要求每個命令列簽入都使用「個人存取權杖」，而不是密碼。當 GitHub 提示輸入您的密碼時，請改為輸入 PAT。關於更多資訊，請參閱 GitHub 文件 。

此外，您也可以使用 SSH (USE_SSH=true) 登入。

觸發 GitHub Actions 進行部署

GitHub Actions可讓您自動化、自訂化及執行存放庫中的軟體開發工作流程。

下列工作流程範例假設您的網站原始程式碼位於存放庫的main分支（原始分支為main），而您的發佈來源已設定為使用自訂 GitHub Actions 工作流程發佈。

我們的目標是

1. 當向main提出新的拉取請求時，有一個操作可以確保網站建立成功，但不會實際部署。這項工作會稱為test-deploy。
2. 當拉取請求合併到main分支或有人直接推送至main分支時，它會建立並部署至 GitHub Pages。這項工作會稱為deploy。

以下為兩個使用 GitHub Actions 部署文件的方法。根據部署存放庫的位置，請選擇下列相關的標籤。

• 原始程式碼存放庫和部署存放庫是相同的存放庫。
• 部署存放庫是一個遠端的存放庫，和原始程式碼存放庫不同。這個場景的說明假設發佈來源是gh-pages分支。

相同

雖然您可以在同一個工作流程檔案中定義這兩項工作，但原始deploy工作流程在公關檢查套件狀態中總是會被列為已略過，這並非實際狀態的指標，而且對評閱流程沒有幫助。因此，我們建議將它們管理為兩個獨立的工作流程。

GitHub 動作檔案

新增這兩個工作流程檔案

調整適合您的設定參數

這些檔案假設您使用 Yarn。如果您使用 npm，則將cache: yarn、yarn install --frozen-lockfile、yarn build變更為cache: npm、npm ci、npm run build。

如果您的 Docusaurus 專案不在您的存放庫根目錄中，您可能需要設定預設工作目錄，並相應地調整路徑。

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build website
        run: yarn build

      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: Deploy to GitHub Pages
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

.github/workflows/test-deploy.yml

name: Test deployment

on:
  pull_request:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  test-deploy:
    name: Test deployment
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Test build website
        run: yarn build

遠端

跨存放庫發佈的設定較困難，因為您需要推送至另一個有權限檢查的存放庫。我們將使用 SSH 執行驗證。

1. 產生一個新的 SSH 金鑰。由於此 SSH 金鑰將用於 CI，請務必不要輸入任何通行碼。
2. 預設情況下，您的公開金鑰應已建立在 ~/.ssh/id_rsa.pub；否則，請使用您在上一步驟中提供的名稱將金鑰新增到 GitHub 部署金鑰。
3. 使用 pbcopy < ~/.ssh/id_rsa.pub 將金鑰複製到剪貼簿，並在部署儲存庫中將它貼上為 部署金鑰。如果命令列對您無效，請複製檔案內容。儲存部署金鑰前，勾選 [允許寫入存取權]。
4. 您需要您的私人金鑰作為 GitHub 機密，以允許 Docusaurus 為您執行部署。
5. 使用 pbcopy < ~/.ssh/id_rsa 複製您的私人金鑰，並在您的原始碼儲存庫上貼上名稱為 GH_PAGES_DEPLOY 的 GitHub 機密。如果命令列對您無效，請複製檔案內容。儲存您的機密。
6. 在 .github/workflows/ 中建立您的 文件工作流程檔案。在本範例中，檔案為 deploy.yml。

至此，您應已取得

• 設定有私人 SSH 金鑰作為 GitHub 機密的原始碼儲存庫，以及
• 在 GitHub 部署金鑰中設定有公開 SSH 金鑰的部署儲存庫。

GitHub 動作檔案

警告

請務必將 [email protected] 替換為您的 GitHub 電子郵件，並將 gh-actions 替換為您的名稱。

此檔案假設您使用 Yarn。如果您使用 npm，請將 cache: yarn、yarn install --frozen-lockfile、yarn build 分別變更為 cache: npm、npm ci、npm run build。

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  test-deploy:
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Test build website
        run: yarn build
  deploy:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn
      - uses: webfactory/ssh-[email protected]
        with:
          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
      - name: Deploy to GitHub Pages
        env:
          USE_SSH: true
        run: |
          git config --global user.email "[email protected]"
          git config --global user.name "gh-actions"
          yarn install --frozen-lockfile
          yarn deploy

網站未正確部署？

推播至主控端後，如果您未在預期的位置看到發佈的網站（例如，它顯示「這裡沒有 GitHub Pages 網站」，或顯示儲存庫的 README.md 檔案），請嘗試以下步驟

• 等待約三分鐘並重新整理。GitHub Pages 可能需要幾分鐘才能擷取新檔案。
• 查看儲存庫的登入頁面，最後一個提交標題旁是否有一個綠色的勾勾，表示 CI 已通過。如果您看到一個叉號，表示建置或部署失敗，您應查看記錄取得更多除錯資訊。
• 點一下勾號，並確定你看到「佈署到 GitHub Pages」的工作流程。諸如「網頁建置及佈署 / 佈署」之名稱為 GitHub 的預設工作流程，表示你的自訂佈署工作流程完全無法觸發。請確認 YAML 檔案放在 .github/workflows 資料夾底下，並且觸發條件設定正確（例如，假設你的預設分支是「master」而不是「main」，你必須變更 on.push 屬性）。
• 在你的存放區的「設定」>「網頁」，確認「來源」（這是佈署檔案的來源，而不是我們用語中的「來源」）已設定為「gh-pages」+「/（根目錄）」；原因在於我們使用 gh-pages 作為佈署分支。

如果你正在使用自訂網域

• 如果你正在使用自訂網域，請驗證你已設定正確的 DNS 記錄。請參閱 GitHub 網頁關於自訂網域及 GitHub 網頁設定的自訂網域文件。此外，請注意，DNS 變更在網路上傳播可能最多需要 24 小時。

使用 Travis CI 觸發佈署

每個新的提交提交到原始碼管理時，通常會使用持續整合 (CI) 服務來執行例行工作。這些工作可能包含執行單元測試及整合測試，自動化建置、發佈套件至 npm，以及將變更佈署至你的網站。你需要做的只有在每次你的網站更新時，呼叫 yarn deploy 腳本即可自動化網站佈署。以下區段涵蓋如何使用 Travis CI（一個流行的持續整合服務提供者）執行此操作。

1. 前往 https://github.com/settings/tokens 以產生一個新的 個人取用權杖。建立權杖時，請授予它 repo 範圍，這樣它才具有需要的權限。
2. 使用你的 GitHub 帳號，從 Travis CI 市集 將 Travis CI 應用程式新增到你想要啟用的存放區。
3. 開啟你的 Travis CI 儀表板。URL 看起來像是 https://travis-ci.com/USERNAME/REPO，並瀏覽到存放區的 更多選項 > 設定 > 環境變數 區段。
4. 建立一個新的環境變數，命名為 GH_TOKEN，而你的新產生權杖作為其值，再建立 GH_EMAIL（你的電子郵件地址）以及 GH_NAME（你的 GitHub 使用者名稱）。
5. 在你的存放區根目錄建立一個 .travis.yml，並輸入以下內容

.travis.yml

language: node_js
node_js:
  - 18
branches:
  only:
    - main
cache:
  yarn: true
script:
  - git config --global user.name "${GH_NAME}"
  - git config --global user.email "${GH_EMAIL}"
  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
  - yarn install
  - GIT_USER="${GH_NAME}" yarn deploy

現在，每當有一個新 commit 回到 main 時，Travis CI 將會執行你的測試套件，如果一切都通過了，你的網站將會透過 yarn deploy 腳本佈署。

使用 Buddy 引發佈署

Buddy 是一個易於使用的 CI/CD 工具，讓你能夠自動化將你的入口網站佈署到不同的環境，包括 GitHub Pages。

按照以下步驟建立一個管線，每當你將變更推送到專案的已選取分支時，就會自動佈署出一個新版網站

1. 前往 https://github.com/settings/tokens 以產生一個新的 個人取用權杖。建立權杖時，請授予它 repo 範圍，這樣它才具有需要的權限。
2. 登入你的 Buddy 帳戶並建立一個新專案。
3. 選擇 GitHub 作為你的 git 代管提供者，並選取包含你的網站程式碼的儲存庫。
4. 使用左側導覽面板，切換到 Pipelines 檢視。
5. 建立一個新管線。定義它的名稱，將觸發模式設為 On push，並選取觸發管線執行的分支。
6. 新增一個 Node.js 動作。
7. 在動作的終端機中新增這些指令

GIT_USER=<GH_PERSONAL_ACCESS_TOKEN>
git config --global user.email "<YOUR_GH_EMAIL>"
git config --global user.name "<YOUR_GH_USERNAME>"
yarn deploy

在建立這個簡單的管線後，推送到你已選取分支的每個新 commit 都會使用 yarn deploy 將你的網站佈署到 GitHub Pages。閱讀 此指引 進一步瞭解如何為 Docusaurus 設定 CI/CD 管線。

使用 Azure Pipelines

1. 如果你還沒註冊，請於 Azure Pipelines 報名。
2. 建立一個組織。在組織中，建立一個專案並連線你的 GitHub 儲存庫。
3. 前往 https://github.com/settings/tokens 並產生一個新的 個人存取權章，範圍為 repo。
4. 在專案頁面（看起來像 https://dev.azure.com/ORG_NAME/REPO_NAME/_build），使用以下文字建立一個新管線。另外，按一下編輯並新增一個名為 GH_TOKEN 的新環境變數，將你新產生的權章做為它的值，然後 GH_EMAIL（你的電子郵件地址）和 GH_NAME（你的 GitHub 使用者名稱）。確定將它們標記為秘密。或者，你也可以在儲存庫根目錄新增一個名為 azure-pipelines.yml 的檔案。

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    persistCredentials: true

  - task: NodeTool@0
    inputs:
      versionSpec: '18'
    displayName: Install Node.js

  - script: |
      git config --global user.name "${GH_NAME}"
      git config --global user.email "${GH_EMAIL}"
      git checkout -b main
      echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
      yarn install
      GIT_USER="${GH_NAME}" yarn deploy
    env:
      GH_NAME: $(GH_NAME)
      GH_EMAIL: $(GH_EMAIL)
      GH_TOKEN: $(GH_TOKEN)
    displayName: Install and build

使用 Drone

1. 建立新 SSH 密鑰，作為專案的佈署金鑰。
2. 為私密金鑰和公開金鑰命名，以保持其特殊性，且不會覆寫其他SSH 金鑰。
3. 前往`https://github.com/USERNAME/REPO/settings/keys`，並貼上您剛剛產生的公開金鑰，新增佈署金鑰。
4. 開啟 Drone.io 儀表板並登入。該網址應該是類似的`https://cloud.drone.io/USERNAME/REPO`。
5. 按一下儲存庫，按一下啟用儲存庫，並新增稱為`git_deploy_private_key` 的機密，其中包含您剛剛產生的私密金鑰值。
6. 在儲存庫根目錄建立`.drone.yml`，其中包含下方文字。

.drone.yml

kind: pipeline
type: docker
trigger:
  event:
    - tag
- name: Website
  image: node
  commands:
    - mkdir -p $HOME/.ssh
    - ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
    - echo "$GITHUB_PRIVATE_KEY" > "$HOME/.ssh/id_rsa"
    - chmod 0600 $HOME/.ssh/id_rsa
    - cd website
    - yarn install
    - yarn deploy
  environment:
    USE_SSH: true
    GITHUB_PRIVATE_KEY:
      from_secret: git_deploy_private_key

現在，只要您在 GitHub 推播新標籤，此觸發器即會啟動 Drone CI 工作，用於發佈您的網站。

佈署至 Flightcontrol

Flightcontrol 是一種服務，可自動建立並將您的網頁應用程式佈署至 AWS Fargate，直接從您的 Git 儲存庫執行。它讓您可以充分存取、檢查和執行基礎結構變更，不受傳統 PaaS 的限制。

請遵循Flightcontrol 的逐步 Docusaurus 指南開始使用。

佈署至 Koyeb

Koyeb 是個開發人員友善的伺服器端平臺，可全球佈署應用程式。此平臺讓您可以透過基於 Git 的佈署、原生自動擴充、全球邊緣網路，以及內建的服務網路和探索，無縫執行 Docker 容器、網頁應用程式和 API。請參考Koyeb 的 Docusaurus 佈署指南開始使用。

佈署至 Render

Render 提供免費的靜態網站寄存，使用完全管理式 SSL、自訂網域、全球 CDN，以及從您的 Git 儲存庫持續自動佈署。請遵循Render 的 Docusaurus 佈署指南，僅需幾分鐘就能開始使用。

佈署至 Qovery

Qovery 是一個完全託管的雲端平台，執行於你的 AWS、Digital Ocean 和 Scaleway 帳戶上，可以在一處主機靜態網站、後端 API、資料庫、cron 作業和所有其他應用程式。

1. 建立一個 Qovery 帳戶。如果你還沒有帳戶，請瀏覽 Qovery 儀表板 建立帳戶。
2. 建立一個專案。
   • 按一下「**建立專案**」並為你的專案命名
   • 按一下「**下一步**」。
3. 建立一個新環境。
   • 按一下「**建立環境**」並輸入名稱（例如準備環境、製作環境）。
4. 新增一個應用程式。
   • 按一下「**建立一個應用程式**」，輸入名稱並選擇你的 GitHub 或 GitLab 存放庫，其中存放你的 Docusaurus 應用程式。
   • 定義主要分支名稱和根目錄應用程式路徑。
   • 按一下「**建立**」，在建立應用程式之後
   • 導航至你的應用程式「**設定**」
   • 選擇「**通訊埠**」
   • 新增你的 Docusaurus 應用程式所使用的通訊埠
5. 佈署
   • 現在你只需要導航至你的應用程式並按一下「**佈署**」即可。

就這樣。查看狀態並等待應用程式佈署完成。若要瀏覽器中開啟應用程式，請按一下應用程式概觀中的「**動作**」與「**開啟**」。

佈署至 Hostman

Hostman 讓你免費主機靜態網站。Hostman 自動執行所有作業，你只需要連線你的存放庫並遵循下列簡單步驟

1. 建立服務。

   • 若要佈署 Docusaurus 靜態網站，請按一下 儀表板 左上角的「**建立**」，然後選擇「**前端應用程式或靜態網站**」。

2. 選擇要佈署的專案。

   • 如果您使用 GitHub、GitLab 或 Bitbucket 帳戶登入 Hostman，您將會看到存放庫與專案，包括私人專案。

   • 選擇您要佈署的專案。它必須包含一個資料夾，其中放有專案的檔案 （例如 website）。

   • 若要存取不同的存放庫，請按一下「**連接其他存放庫**」。

   • 如果您沒有使用 Git 帳戶憑證登入，您現在可以存取必要的帳戶，然後選擇專案。

3. 設定組建設定。

   • 接下來，「**網站自訂**」視窗將會出現。從架構清單中選擇「**靜態網站**」選項。

   • 「**應用程式資料夾**」會指出組建後將會包含專案檔案的資料夾。如果您在步驟 2 選擇了存放庫與網站內容 (或 my_website) 資料夾，您可將此欄留空。

   • Docusaurus 的標準組建指令為

     npm

     npm run build

     Yarn

     yarn build

     pnpm

     pnpm run build

   • 如果您需要，可以修改編譯指令。您可以輸入多個指令，每個指令之間以 && 分隔。

4. 部署。

   • 按一下部署開始編譯處理程序。

   • 開始後，您將進入部署記錄。如果程式碼有任何問題，您可以於記錄中獲得警告或錯誤訊息，指出問題原因。通常，記錄會包含您需要的偵錯資料。

   • 部署完成後，您將收到電子郵件通知，並會看見記錄分錄。一切都完成了！您的專案已完成並準備就緒。

部署到 Surge

Surge 是一個 靜態網路代管平台，您可以使用它於數秒內從指令行部署 Docusaurus 專案。將專案部署到 Surge 非常簡單且免費（包含自訂網域和 SSL 憑證）。

使用 Surge 執行下列步驟，於數秒內部署您的應用程式

1. 首先，使用 npm 安裝 Surge，請執行以下指令
   npm

   npm install -g surge

   Yarn

   yarn global add surge

   pnpm

   pnpm add -g surge
2. 執行指令，以在專案的根目錄中，為您的網站產生生產環境中的靜態檔案
   npm

   npm run build

   Yarn

   yarn build

   pnpm

   pnpm run build
3. 然後，於專案的根目錄中執行這個指令

   surge build/

Surge 的首次使用者將會受到提示，在指令行建立帳戶（只會發生一次）。

確認您想要發表的網站位於 build 目錄之下。系統會隨時給予一個隨機產生的子網域 *.surge.sh 子網域（可以編輯）。

使用您的網域

如果您有一個網域名稱，可以使用以下指令部署您的網站

surge build/ your-domain.com

您的網站現在已免費部署於 subdomain.surge.sh 或 your-domain.com，視您選擇的方法而定。

設定 CNAME 檔案

使用以下指令，儲存您的網域於 CNAME 檔案中，作為未來部署之用

echo subdomain.surge.sh > CNAME

您可以使用指令 surge 部署日後任何其他變更。

部署到 Stormkit

您可以將 Docusaurus 專案部署到 Stormkit，這是專為靜態網站、單頁應用程式 (SPA) 和無伺服器函式設計的部署平台。如需詳細指示，請參閱這份 指南。

部署到 QuantCDN

1. 安裝 Quant CLI
2. 透過註冊建立一個 QuantCDN 帳戶
3. 使用 quant init 來初始化你的專案，並填寫你的登入資料

   quant init
4. 部署你的網站。

   quant deploy

參閱 文件 和 部落格 以取得有關部署至 QuantCDN 的更多範例和用例。

部署至 Layer0

Layer0 是一個多合一平台，可用於開發、部署、預覽、體驗、監視以及執行你的無伺服器前端。Layer0 著重於大型動態網站，並透過 EdgeJS（一個基於 JavaScript 的內容傳遞網路）、預測預先擷取以及效能監控，提供最佳化效能。Layer0 提供免費層級。只需幾分鐘，就能開始使用，只要逐步按照 Layer0 部署 Docusaurus 指南 即可。

部署至 Cloudflare Pages

Cloudflare Pages 是前端開發人員用於協作和部署網站的 Jamstack 平台。只需幾分鐘，就能開始使用，只要逐步按照 這篇文章 即可。

部署至 Azure Static Web Apps

Azure Static Web Apps 是一項服務，可自動將全端點 Web 應用程式從程式碼存放庫直接建置並部署至 Azure，進而簡化 CI/CD 開發人員體驗。Static Web Apps 會將 Web 應用程式的靜態資源與其動態 (API) 端點分開。靜態資源會由全球分散的內容伺服器提供服務，讓用戶端更快地使用附近的伺服器來擷取檔案。動態 API 會使用成本效益較高、依需求縮放的基於活動的函式方法，利用無伺服器架構來進行擴充。只需幾分鐘，就能開始使用，只要逐步按照 這份逐步指南 即可。

部署至 Kinsta

Kinsta Static Site Hosting 讓你能夠免費部署多達 100 個靜態網站，提供自訂網域連同 SSL、每個月 100 GB 頻寬，以及超過 260 個 Cloudflare CDN 位置。

只需幾個步驟，就能開始使用，只要逐步按照我們的 Kinsta 上的 Docusaurus 文章即可。