Deploying

接下来的指南基于以下条件:

  • 你的文档放置在你项目的docs目录下;
  • 你使用的是默认的构建输出位置(.vitepress/dist);
  • VitePress以本地依赖的形式被安装到你的项目中,并且配置了如下的 npm 脚本:
{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}

构建文档

你可以运行 yarn docs:build 命令来构建文档。

$ yarn docs:build

默认情况下,构建输出位于.vitepress/dist。你可以部署dist文件夹到任何你首选平台。

本地测试

一旦你构建了这些文档,你就可以通过运行yarn docs:serve命令来进行本地测试。

$ yarn docs:build
$ yarn docs:serve

serve 命令会启动一个本地静态web服务器,该服务器提供在 http://localhost:5000访问.vitepress/dist中文件的服务。这是一个在本地环境中检查产品构建是否正常的简单方法。

你可以通过传入--port参数来配置服务器的端口。

{
  "scripts": {
    "docs:serve": "vitepress serve docs --port 8080"
  }
}

现在 docs:serve 方法将会启动在 http://localhost:8080上。

GitHub Pages

  1. docs/.vitepress/config.js设置正确的base

    如果你想部署到 https://<USERNAME>.github.io/, 你可以省略这一步,因为 base 默认为 '/'

    如果你想部署到 https://<USERNAME>.github.io/<REPO>/, 比如你的仓库是 https://github.com/<USERNAME>/<REPO>, 那么需要设置base'/<REPO>/'

  2. 在你的项目中创建包含如下内容的 deploy.sh文件(请自行判断去掉高亮行的注释)。













 






 


 



#!/usr/bin/env sh

# 忽略错误
set -e

# 构建
npm run docs:build

# 进入待发布的目录
cd docs/.vitepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果部署到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果是部署到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

TIP

你可以在你的持续集成的设置中,设置在每次 push 代码时自动运行上述脚本。

GitHub Pages 和 Travis CI

  1. docs/.vitepress/config.js中设置正确的 base

如果你想部署到 https://<USERNAME or GROUP>.github.io/, 你可以省略这一步,因为 base 默认为 '/'

如果你想部署到 https://<USERNAME or GROUP>.github.io/<REPO>/, 比如你的仓库是 https://github.com/<USERNAME>/<REPO>, 那么需要设置base'/<REPO>/'

  1. 在项目根目录创建一个名为.travis.yml的文件。

  2. 本地运行 yarnnpm install ,提交生成的lock文件 ( yarn.lockpackage-lock.json)。

  3. 使用GitHub Pages部署提供的程序模板,遵循 Travis CI 文档.

language: node_js
node_js:
  - lts/*
install:
  - yarn install # npm ci
script:
  - yarn docs:build # npm run docs:build
deploy:
  provider: pages
  skip_cleanup: true
  local_dir: docs/.vitepress/dist
  # 在 GitHub 中生成,用于允许 Travis 向你的仓库推送代码。在 Travis 的项目设置页面进行配置,设置为 secure variable
  github_token: $GITHUB_TOKEN
  keep_history: true
  on:
    branch: master

GitLab Pages 和 GitLab CI

  1. docs/.vitepress/config.js中设置正确的 base

如果你想部署到 https://<USERNAME or GROUP>.gitlab.io/, 你可以省略这一步,因为 base 默认为 '/'

如果你想部署到 https://<USERNAME or GROUP>.gitlab.io/<REPO>/, 比如你的仓库是 https://gitlab.com/<USERNAME>/<REPO>, 那么需要设置base'/<REPO>/'

  1. .vitepress/config.js 中设置destpublic

  2. 在你的项目根目录创建一个名为.gitlab-ci.yml并且包含以下内容的文件。这样,不论何时你修改文件内容,程序会自动构建并部署到站点。

image: node:10.22.0
pages:
  cache:
    paths:
      - node_modules/
  script:
    - yarn install # npm install
    - yarn docs:build # npm run docs:build
  artifacts:
    paths:
      - public
  only:
    - master

Netlify

  1. Netlify上,使用一下配置从GitHub设置一个新项目:
  • Build Command: vitepress build docs 或者 yarn docs:buildnpm run docs:build
  • Publish directory: docs/.vitepress/dist
  1. 点击部署按钮

Google Firebase

  1. 确保你安装了 firebase-tools

  2. 在你项目根目录下创建 firebase.json and .firebaserc,分别包含以下内容:

firebase.json:

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

.firebaserc:

{
 "projects": {
   "default": "<YOUR_FIREBASE_ID>"
 }
}
  1. 在运行yarn docs:buildnpm run docs:build, 使用firebase deploy部署。

Surge

  1. 首先安装 surge

  2. 运行 yarn docs:buildnpm run docs:build.

  3. 通过 surge docs/.vitepress/dist部署到Surge。

你也可以通过surge docs/.vitepress/dist yourdomain.com部署到 自定义域名

Heroku

  1. 安装 Heroku CLI.

  2. 通过signing up创建账户。

  3. 运行 heroku login 并填入认证信息。

$ heroku login
  1. 在项目的根目录创建 static.json包含以下内容:

static.json:

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

以下是站点配置,参见heroku-buildpack-static

  1. 设置 Heroku git远程仓库:
# version change
$ git init
$ git add .
$ git commit -m "My site ready for deployment."

# creates a new app with a specified name
$ heroku apps:create example

# set buildpack for static sites
$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git
  1. 部署站点:
# publish site
$ git push heroku master

# opens a browser to view the Dashboard version of Heroku CI
$ heroku open

Vercel

在通过Vercel for Git部署VitePress之前,确保已经发布的Git仓库。

打开https://vercel.com/import/git根据你的选择的Git(GitHub、 GitLab 或 BitBucket)引入项目到Vercel。 接下来按照向导选择包含package.json文档的项目根目录,然后使用yarn docs:buildnpm run docs:build重新执行构建步骤并且设置输出目录为./docs/.vitepress/dist

Override Vercel Configuration

导入项目后,对分支的所有后续推送都将生成预览部署,而对生产分支所做的所有更改(通常为“main”)将导致生产部署。

一旦部署完毕,你将获得一个URL来查看你的应用程序,如 https://vitepress.vercel.app