查看“VuePress部署”的源代码

下述的指南基于以下条件：

* Markdown 源文件放置在你项目的 <code>docs</code> 目录；
* 使用的是默认的构建输出目录 (<code>.vuepress/dist</code>) ；
* 使用 [https://pnpm.io/zh/ pnpm] 作为包管理器，当然也支持使用 npm 或 yarn 。
* VuePress 作为项目依赖安装，并在 <code>package.json</code> 中配置了如下脚本：

<pre lang="json">{
  "scripts": {
    "docs:build": "vuepress build docs"
  }
}</pre>
<span id="github-pages"></span>
== GitHub Pages ==

<ol style="list-style-type: decimal;">
<li><p>设置正确的 base 选项。</p>
<p>如果你准备发布到 <code>https://&lt;USERNAME&gt;.github.io/</code> ，你可以省略这一步，因为 <code>base</code> 默认就是 <code>&quot;/&quot;</code> 。</p>
<p>如果你准备发布到 <code>https://&lt;USERNAME&gt;.github.io/&lt;REPO&gt;/</code> ，也就是说你的仓库地址是 <code>https://github.com/&lt;USERNAME&gt;/&lt;REPO&gt;</code> ，则将 <code>base</code> 设置为 <code>&quot;/&lt;REPO&gt;/&quot;</code>。</p></li>
<li><p>选择你想要使用的 CI 工具。这里我们以 [https://github.com/features/actions GitHub Actions] 为例。</p>
<p>创建 <code>.github/workflows/docs.yml</code> 文件来配置工作流。</p></li></ol>

::: details 点击展开配置样例

<pre lang="yaml">name: docs

on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
        with:
          # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
          fetch-depth: 0

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          # 选择要使用的 pnpm 版本
          version: 8
          # 使用 pnpm 安装依赖
          run_install: true

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          # 选择要使用的 node 版本
          node-version: 18
          # 缓存 pnpm 依赖
          cache: pnpm

      # 运行构建脚本
      - name: Build VuePress site
        run: pnpm docs:build

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v2
        with:
          # 部署到 gh-pages 分支
          target_branch: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          build_dir: docs/.vuepress/dist
        env:
          # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}</pre>
:::

<div class="tip">

请参考 [https://pages.github.com/ GitHub Pages 官方指南] 来获取更多信息。


</div>
<span id="gitlab-pages"></span>
== GitLab Pages ==

<ol style="list-style-type: decimal;">
<li><p>设置正确的 base 选项。</p>
<p>如果你准备发布到 <code>https://&lt;USERNAME&gt;.gitlab.io/</code> ，你可以省略这一步，因此 <code>base</code> 默认就是 <code>&quot;/&quot;</code> 。</p>
<p>如果你准备发布到 <code>https://&lt;USERNAME&gt;.gitlab.io/&lt;REPO&gt;/</code> ，也就是说你的仓库地址是 <code>https://gitlab.com/&lt;USERNAME&gt;/&lt;REPO&gt;</code> ，则将 <code>base</code> 设置为 <code>&quot;/&lt;REPO&gt;/&quot;</code>。</p></li>
<li><p>创建 <code>.gitlab-ci.yml</code> 文件来配置 [https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/ GitLab CI] 工作流。</p></li></ol>

::: details 点击展开配置样例

<pre lang="yaml"># 选择你要使用的 docker 镜像
image: node:18-buster

pages:
  # 每当 push 到 main 分支时触发部署
  only:
    - main

  # 缓存 node_modules
  cache:
    key:
      files:
        - pnpm-lock.yaml
    paths:
      - .pnpm-store

  # 安装 pnpm
  before_script:
    - curl -fsSL https://get.pnpm.io/install.sh | sh -
    - pnpm config set store-dir .pnpm-store

  # 安装依赖并运行构建脚本
  script:
    - pnpm install --frozen-lockfile
    - pnpm docs:build --dest public

  artifacts:
    paths:
      - public</pre>
:::

<div class="tip">

请参考 [https://docs.gitlab.com/ce/user/project/pages/#getting-started GitLab Pages 官方指南] 来获取更多信息。


</div>