17. 文档自动发布:GitLab Pages 代码改文档同步更新
「GitLab」系列已发布: 00. GitLab 不只是代码托管:一套 DevOps 平台的 6 大核心能力 | 01. GitLab 怎么装最省心?Omnibus/Docker/K8s 三种姿势 | 02. 装完 GitLab 先配啥?管理员视角的初始化设置清单 | 03. GitLab 角色搞不清?Member/Maintainer/Owner 权限全解 | 04. 从零建好第一个 GitLab 项目:权限、变量、CI 配置入门 | 05. GitLab MR 代码审查:Code Review 最佳实践 | 06. CI/CD 到底是什么?GitLab 流水线架构从概念到实战 | 07. Runner 装不好?GitLab Runner 单机/分布式/高可用全攻略 | 08. .gitlab-ci.yml 怎么写?从 Hello World 到生产配置 | 09. 从 0 到 1:Go + React 项目的 GitLab CI/CD 实战部署 | 10. 构建太慢?GitLab 缓存与工件管理:加速构建省时间 | 11. 测试/预发/生产怎么管?GitLab 多环境部署与金丝雀发布 | 12. 安全左移:GitLab SAST/DAST 自动化扫描,漏洞提前拦截 | 13. 镜像仓库不用 Harbor?GitLab Container Registry 一站式管理 | 14. 私有包怎么存?GitLab Package Registry:Maven/PyPI/NPM 全覆盖 | 15. GitLab 挂了怎么办?高可用架构 + 备份恢复业务不中断 | 16. 自动化触发:GitLab Webhooks + API 打通你的工具链 | 17. 文档自动发布:GitLab Pages 代码改文档同步更新(本文)
文档和代码不同步是技术团队通病。GitLab Pages 在流水线里自动构建静态站点,代码一改文档就更新,告别手动搬文档。
前置条件
已掌握基础 CI/CD 配置(第 08-09 篇)。需要启用 GitLab Pages 功能并配置域名。
一、Pages 概述
GitLab Pages 允许你从 GitLab CI/CD Pipeline 托管静态网站。支持的技术栈:
| 技术 | 框架 | 文档生成 |
|---|---|---|
| Vue.js | VuePress, VitePress | VuePress |
| React | Docusaurus, Gatsby | Create React App |
| Hugo | Hugo | Hugo |
| Jekyll | Jekyll | Jekyll |
| MkDocs | MkDocs | MkDocs |
| Hexo | Hexo | Hexo |
| Astro | Astro | Astro |
flowchart TD A[代码仓库] --> B[CI/CD Pipeline] B --> C{构建站点} C --> D[静态文件] D --> E[GitLab Pages] E --> F[访问 URL] subgraph GitLab["GitLab Pages"] G[HTTPS 自动启用] H[CDN 加速] I[自定义域名] end
二、构建配置
2.1 基础配置
pages:
stage: deploy
image: node:20-alpine
before_script:
- npm ci
script:
- npm run docs:build
artifacts:
paths:
- public # 必须是 public 目录
rules:
- if: $CI_COMMIT_BRANCH == "main"
2.2 VuePress 配置
// docs/.vuepress/config.js
module.exports = {
title: 'My Project',
base: '/my-project/', // 项目 Pages 需要 base
themeConfig: {
nav: [
{ text: 'Guide', link: '/guide/' },
{ text: 'API', link: '/api/' }
]
}
}
pages:
stage: deploy
image: ruby:3.3
before_script:
- gem install bundler
- bundle install
script:
- bundle exec jekyll build -d public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == "main"
2.3 Hugo 配置
pages:
stage: deploy
image: klakegg/hugo:ext-alpine
script:
- hugo --destination public
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == "main"
三、Review Apps(每个 MR 独立页面)
review-pages:
stage: deploy
image: node:20-alpine
before_script:
- npm ci
script:
- npm run docs:build
artifacts:
paths:
- public
environment:
name: review/pages/$CI_MERGE_REQUEST_IID
url: https://$CI_PROJECT_ROOT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html
on_stop: stop-review-pages
rules:
- if: $CI_MERGE_REQUEST_ID
stop-review-pages:
stage: .post
environment:
name: review/pages/$CI_MERGE_REQUEST_IID
action: stop
rules:
- if: $CI_MERGE_REQUEST_ID
when: manual
variables:
GIT_STRATEGY: none
四、多分支部署
pages:
script:
- npm run docs:build
- |
if [ "$CI_COMMIT_BRANCH" != "main" ]; then
mkdir -p public/$CI_COMMIT_BRANCH
mv public/*.html public/$CI_COMMIT_BRANCH/
fi
artifacts:
paths:
- public
五、自定义域名
5.1 GitLab 侧配置
项目 → Settings → Pages → New Domain。填域名后勾选 Let’s Encrypt 自动签发,GitLab 自动续期。
5.2 DNS 配置
# CNAME 记录
pages.example.com → <username>.gitlab.io
或
pages.example.com → xx.gitlab.io
六、访问控制
Settings → General → Visibility:Private(仅成员)/ Internal(登录用户)/ Public(所有人)。
GitLab Pages 访问控制 (Premium):
- Private Pages:仅项目成员可访问
- Internal Pages:登录 GitLab 即可访问
- Public Pages:所有人可访问
七、性能优化
7.1 压缩
pages:
script:
- npm run build
- find public -name '*.html' -exec gzip -k {} \;
artifacts:
paths:
- public
expire_in: 30 days
7.2 CDN 缓存
pages:
script:
- npm run build
- |
echo '<meta http-equiv="cache-control" content="max-age=31536000">' >> public/index.html
artifacts:
paths:
- public
八、状态监控
项目 → Deploy → Pages:部署时间、状态、访问 URL、证书状态。
CI/CD → Jobs → Pages Job:部署日志、可下载构建产物预览。
九、Pages 工作流程
sequenceDiagram participant Dev as 开发者 participant GitLab as GitLab participant Build as CI/CD participant Pages as Pages Server participant CDN as CDN Dev->>GitLab: push 代码到 main GitLab->>Build: 触发 Pages Pipeline Build->>Build: 构建静态文件 Build->>Pages: 上传 artifacts Pages->>CDN: 分发到边缘节点 CDN-->>User: 提供访问
十、文章引用
📌 本文首发于微信公众号 【运维知识点滴】——专注运维实战干货,微信搜索“运维知识点滴”或扫下方二维码关注,更新不迷路。
| 微信公众号【运维知识点滴】 | 微信小程序【A5单据合并&大试卷拆分转A4打印】 |
|---|---|
![]() |
![]() |
| 运维实战干货 · 关注追更 | Word 转 PDF · 试卷/发票打印神器 · 免费 |
💡 小程序【A5单据合并&大试卷拆分转A4打印】是干嘛的? 一个 Word 转 PDF 的打印神器,专治“文档版式和打印机对不上”:
- A3 试卷打不出来? 学校发的电子版试卷多是 A3,家用打印机只吃 A4——上传 Word 一键转换:可缩到一页 A4(页数不变),也可对半拆成两张 A4(1:1 原大、字更清晰),两种模式自选;
- 版式不乱:真实渲染引擎原样转换、绝不重排内容,转出的 PDF 和原 Word 排版一致,公式/表格/图片不跑版;
- 两张 A5 单据拼一张 A4:出租车票、火车票等报销凭证拼版后,一次打印、整齐粘贴;
- 隐私省心:无需注册,转换结果留存 5 天、最多下载 5 次即自动删除,不留任何历史记录;
- 微信扫码即用,免费、免安装,支持 doc / docx(≤50MB)。

