Jin Gao

Appearance

部署

指南部署

2024-03-20

Tips

此文档 fork 自 vuepress official doc。

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

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

GitHub Pages

  1. 设置正确的 base 选项。

    如果你准备发布到 https://<USERNAME>.github.io/ ，你可以省略这一步，因为 base 默认就是 "/" 。

    如果你准备发布到 https://<USERNAME>.github.io/<REPO>/ ，也就是说你的仓库地址是 https://github.com/<USERNAME>/<REPO> ，则将 base 设置为 "/<REPO>/"。

  2. 选择你想要使用的 CI 工具。这里我们以 GitHub Actions 为例。

    创建 .github/workflows/docs.yml 文件来配置工作流。

点击展开配置样例
name: docs

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

jobs:
  docs:
    runs-on: ubuntu-latest

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

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # 选择要使用的 node 版本
          node-version: 20
          # 缓存 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@v4
        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 }}

Tips

请参考 GitHub Pages 官方指南 来获取更多信息。

GitLab Pages

  1. 设置正确的 base 选项。

    如果你准备发布到 https://<USERNAME>.gitlab.io/ ，你可以省略这一步，因此 base 默认就是 "/" 。

    如果你准备发布到 https://<USERNAME>.gitlab.io/<REPO>/ ，也就是说你的仓库地址是 https://gitlab.com/<USERNAME>/<REPO> ，则将 base 设置为 "/<REPO>/"。

  2. 创建 .gitlab-ci.yml 文件来配置 GitLab CI 工作流。

点击展开配置样例
# 选择你要使用的 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

Tips

请参考 GitLab Pages 官方指南 来获取更多信息。

Google Firebase

  1. 请确保你已经安装了 firebase-tools。

  2. 在你项目的根目录下创建 firebase.json 和 .firebaserc，并包含以下内容：

    firebase.json:

    {
  "hosting": {
    "public": "./docs/.vuepress/dist",
    "ignore": []
  }
}

    .firebaserc:

    {
  "projects": {
    "default": "<YOUR_FIREBASE_ID>"
  }
}

  3. 在执行了 pnpm docs:build 后, 使用 firebase deploy 指令来部署。

Tips

请参考 Firebase CLI 官方指南 来获取更多信息。

Heroku

  1. 首先安装 Heroku CLI；

  2. 在这里 注册一个 Heroku 账号；

  3. 运行 heroku login 并填写你的 Heroku 认证信息：

    heroku login

  4. 在你的项目根目录中，创建一个名为 static.json 的文件，并包含下述内容：

static.json:

{
  "root": "./docs/.vuepress/dist"
}

这里是你项目的配置，请参考 heroku-buildpack-static 来获取更多信息。

Kinsta

请查看 Set Up VuePress on Kinsta 。

Edgio

请查看 Edgio Documentation > Framework Guides > VuePress 。

Netlify

  1. 前往 Netlify ，从 GitHub 创建一个新项目，并进行如下配置：

    • Build Command: pnpm docs:build
    • Publish directory: docs/.vuepress/dist

  2. 设置 Environment variables 来选择 Node 版本：

    • NODE_VERSION: 18

  3. 点击 deploy 按钮。

Vercel

  1. 前往 Vercel ，从 GitHub 创建一个新项目，并进行如下配置：

    • FRAMEWORK PRESET: Other
    • BUILD COMMAND: pnpm docs:build
    • OUTPUT DIRECTORY: docs/.vuepress/dist

  2. 点击 deploy 按钮。

云开发 CloudBase

云开发 CloudBase 是一个云原生一体化的 Serverless 云平台， 支持静态网站、容器等多种托管能力，并提供简便的部署工具 CloudBase Framework 来一键部署应用。

  1. 全局安装 CloudBase CLI ：

    pnpm install -g @cloudbase/cli

  2. 在项目根目录运行以下命令一键部署 VuePress 应用，在部署之前可以先 开通环境：

    cloudbase init --without-template
cloudbase framework:deploy

CloudBase CLI 首先会跳转到控制台进行登录授权，然后将会交互式进行确认。

确认信息后会立即进行部署，部署完成后，可以获得一个自动 SSL，CDN 加速的网站应用，你也可以搭配使用 GitHub Action 来持续部署 GitHub 上的 VuePress 应用。

也可以使用 cloudbase init --template vuepress 快速创建和部署一个新的 VuePress 应用。

Tips

更多详细信息请查看 CloudBase Framework 的部署项目示例

21 云盒子

请查看 21 云盒子 - 部署一个 VuePress 静态网页。