xqh-vue-ui

# 文档部署

# 文档构建

  1. 文档放置在项目的 docs 目录中，使用的是默认的构建输出位置；

  2. 配置npm scripts；

    {
  "scripts": {
    "docs:build": "vuepress build docs"
  }
}

  3. 运行npm run docs:build，生成静态文件位于docs/.vuepress/dist下。

# GitHub Pages

  1. 先将文档项目push到GitHub仓库（xqh-vue-ui-doc）；

  2. 在 docs/.vuepress/config.js 中设置正确的 base；

    • 如果打算发布到 https://<USERNAME>.github.io/，则可以省略这一步，因为 base 默认即是 "/"；
    • 如果打算发布到 https://<USERNAME>.github.io/<REPO>/（也就是说仓库在 https://github.com/<USERNAME>/<REPO>），则将 base 设置为 "/<REPO>/"。
    base: '/xqh-vue-ui-doc/'

  3. 在项目根目录创建deploy.sh 文件；

    # 部署到GitHub Pages

#! /bin/bash

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

git init
git add -A
git commit -m '部署静态页面'

# 如果发布到 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

git push -f git@github.com:lanyuxqh/xqh-vue-ui-doc.git master:gh-pages

cd -

  4. 配置npm scripts；

    {
  "scripts": {
    "deploy": "sh deploy.sh"
  }
}

  5. 运行npm run deploy，把静态文件推送到远端仓库的gh-pages分支下，就可以通过https://lanyuxqh.github.io/xqh-vue-ui-doc/访问文档啦。每次写完文章去执行 npm run deploy 这行命令就可以了。

# GitHub Actions

现在我们写一篇文章并且发布到 GitHub Pags 需要手动执行sh脚本，使用GitHub Actions 可以帮助我们简化流程，让写完一篇文章后只需要将代码上传至 GitHub 就能帮我们自动构建部署到线上。

GitHub Actions (opens new window) 是 GitHub 的持续集成服务 (opens new window)。

持续集成（Continuous integration，简称CI）：频繁地（一天多次）将代码集成到主干。目的：就是让产品可以快速迭代，同时还能保持高质量。

  • 持续集成由很多操作组成，比如抓取代码、运行测试、登录远程服务器，发布到第三方服务等等。GitHub 把这些操作就称为 actions。

  • GitHub Actions 最特别的地方：允许开发者把每个操作写成独立的脚本文件，存放到代码仓库，使得其他开发者可以引用。如果你需要某个 action，不必自己写复杂的脚本，直接引用他人写好的 action 即可，整个持续集成过程，就变成了一个 actions 的组合。

  • GitHub Actions 术语：

    • workflow （工作流程）：持续集成一次运行的过程，就是一个 workflow。
    • job （任务）：一个 workflow 由一个或多个 jobs 构成，含义是一次持续集成的运行，可以完成多个任务。
    • step（步骤）：每个 job 由多个 step 构成，一步步完成。
    • action （动作）：每个 step 可以依次执行一个或多个命令（action）。

  • workflow 文件：GitHub Actions 的配置文件

    • 文件后缀名统一为.yml，存放在代码仓库的.github/workflows目录。
    • 一个库可以有多个 workflow 文件；
    • GitHub 只要发现.github/workflows目录里面有.yml文件，就会自动运行该文件。

  1. 在 GitHub 上创建个人访问令牌 ACCESS_TOKEN

  2. 编写 workflow 文件

    # name字段，表示 workflow 的名称。如果省略该字段，默认为当前 workflow 的文件名。
name: docs

# on字段，指定触发 workflow 的条件，通常是某些事件。
on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

# jobs字段，表示要执行的一项或多项任务。
jobs:
  docs:
    # runs-on字段，指定运行所需要的虚拟机环境。（必填字段）
    runs-on: ubuntu-latest

    # steps字段，指定每个 Job 的运行步骤，可以包含一个或多个步骤。
    steps:
      - uses: actions/checkout@v2
        with:
          # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          # 选择要使用的 node 版本
          node-version: '14'

      # 缓存 node_modules
      - name: Cache dependencies
        uses: actions/cache@v2
        id: yarn-cache
        with:
          path: |
            **/node_modules
          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-

      # 如果缓存没有命中，安装依赖
      - name: Install dependencies
        if: steps.yarn-cache.outputs.cache-hit != 'true'
        run: yarn

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

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@3.7.1
        with:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}  # 在 GitHub 上创建个人访问令牌 ACCESS_TOKEN
          # 部署到 gh-pages 分支
          BRANCH: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          FOLDER: docs/.vuepress/dist

  3. 每次写完文章push代码，回到GitHub上点击actions，发现项目已经在自动构建了。

# 遇到的问题

  1. 使用npm run docs:dev编写完文档后，需要运行npm run docs:build将其build打包，然后发布到服务器上。然而在build的过程中，报了如下的错误：

    ReferenceError: window is not defined
    at Object.3897 (node_modules/xqh-vue-ui/dist/xqh-vue-ui.umd.min.js:1:75887)
    at i (node_modules/xqh-vue-ui/dist/xqh-vue-ui.umd.min.js:1:91183)
    at server-bundle.js:52124:92091
    at server-bundle.js:52124:161769
    at server-bundle.js:52124:161774
    at server-bundle.js:52124:37
    at Object.<anonymous> (node_modules/xqh-vue-ui/dist/xqh-vue-ui.umd.min.js:1:246)
    at __webpack_require__ (webpack/bootstrap:25:0)
    at Module.<anonymous> (server-bundle.js:129480:26)
    at __webpack_require__ (webpack/bootstrap:25:0)
    at Object.<anonymous> (server-bundle.js:52399:18)
    at __webpack_require__ (webpack/bootstrap:25:0)
    at server-bundle.js:118:18
    at Object.<anonymous> (server-bundle.js:121:10)
    at evaluateModule (/Users/xqh/program/xqh-frontend-project/xqh-vue-ui-doc/node_modules/vue-server-renderer/build.dev.js:7948:25)
    at /Users/xqh/program/xqh-frontend-project/xqh-vue-ui-doc/node_modules/vue-server-renderer/build.dev.js:8000:26
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! xqh-vue-ui-doc@1.0.0 docs:build: `vuepress build docs`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the xqh-vue-ui-doc@1.0.0 docs:build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/xqh/.npm/_logs/2022-07-26T02_42_04_868Z-debug.log
    • 原因：vuepress build生成的静态文件都是通过node服务端渲染完成的。因此，当组件中不是在beforeMount 或者 mounted 钩子中访问浏览器 / DOM 的 API时，就会有问题。
    • 解决：
      • 对Markdown文件中引入的组件，使用内置的 <ClientOnly> 组件包裹。（这一步不设置，会导致文档刷新后样式丢失！）
      • 组件库的引入放在mounted钩子中。

  2. 发布到线上后发现css样式丢失，经查看发现访问路径发生404的有可能是项目引用路径错误，本文没有修改过打包路径，用的是默认路径 docs/.vuepress/dist。

  3. 本文所使用的actions版本是v3，以往教程中所讲到的使用的是JamesIves/github-pages-deploy-action v2版本，新版本语法已经发生了变化，如果继续使用就会发生错误。

  4. ACCESS_TOKEN 一定要和github上的sectets上的名称相同。

← 组件按需引入 →