1 篇博文 含有标签「docusaurus」

概述​

  这是部署好本站的第一篇文章，记录本站部署过程中踩坑的问题点。参考官方文档，这里采用源代码仓库跟静态文件仓库分离的方式部署，把静态文件托管到Github Pages上，并使用Github Actions触发部署。官方文档写的比较详细的内容本文会简化或者直接省略，把重点放在官方文档写的比较绕、不容易理解以及容易出错的地方，尽量做到简单易懂。

包含以下内容：

• 使用两个仓库时部署验证问题。
• 两个仓库分支配置问题。
• Github Actions触发部署，遇到的问题，以及解决方式。
• Github Pages域名设置，如何设置DNS，以及去除www前缀。

生成项目​

使用默认模板生成项目​

npx create-docusaurus@latest my-website classic

运行开发服务器

cd my-website
npm run start

默认情况下，浏览器窗口将在 http://localhost:3000 打开。

修改配置​

module.exports = {
  // ...
  url: 'https://endiliey.github.io', // Your website URL
  baseUrl: '/',
  projectName: 'endiliey.github.io',
  organizationName: 'endiliey',
  trailingSlash: false,
  deploymentBranch: 'main',
  // ...
};

部署​

创建 Github 仓库​

创建两个github仓库：

• my-website用来存放整个项目源代码，可以设置为私有仓库。

• username.github.io参照 Github Pages 文档创建，用来存放生成的静态文件，需要设置为公开仓库。

生成 ssh 密钥。​

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

可以使用-f 指定目录和密钥名字，以免覆盖现有ssh密钥，需要先创建.ssh目录。例如以下命令会在当前目录生成ssh密钥。

mkdir .ssh
`ssh-keygen -f ./.ssh/id_rsa -t rsa -b 4096 -C "your_email@example.com"`

添加 Deploy keys​

添加公钥到静态文件仓库的Deploy keys。

添加 Actions secrets​

添加私钥到源代码仓库的Actions secrets and variables。

创建工作流文件​

在源代码仓库根目录，创建工作流文件。

name: Deploy to GitHub Pages

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

jobs:
  test-deploy:
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        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@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: yarn
      - uses: webfactory/ssh-agent@v0.5.0
        with:
          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
      - name: Deploy to GitHub Pages
        env:
          USE_SSH: true
        run: |
          git config --global user.email "actions@github.com"
          git config --global user.name "gh-actions"
          yarn install --frozen-lockfile
          yarn deploy

推送 my-website 到远程​

到这里，两个远程仓库都应该是空的，把本地my-website文件夹内的内容，推送到远程my-website仓库，使用默认main分支。

检查静态文件仓库​

如果上述操作一切顺利的话，本地my-website推送到远程仓库my-website的main分支之后，会自动触发Github Actions工作流。工作流会生成静态文件，并把静态文件推送到静态文件仓库的main分支。

修改静态文件仓库配置​

修改静态文件仓库的Github Pages配置。

添加DNS记录​

域名访问分为两种情况

• 使用 www.you-domain-name.com 子域

• 使用 you-domain-name.com 主域

使用www子域名，只需设置www子域的CNAME记录解析到username.github.io，并且在my-website仓库里的./static文件夹下，添加CNAME文件，文件内容为www.you-domain-name.com。此时域名主记录会自动跳转到www子域。

使用主域，需要添加主机记录解析到github服务器的IP，并设置www子域的CNAME记录解析到username.github.io，并且在my-website仓库里的./static文件夹下，添加CNAME文件，文件内容为you-domain-name.com。此时www子域会自动跳转到主域。

检查工作流触发和运行状态​

以上操作如无错误，则可以直接访问you-domain-name.com查看页面，直接更新my-website的main分支，即可触发工作流，自动更新Github Pages页面。