Vuepress 配置指南
通过 GitHub API 将文章发布到 Vuepress1 静态博客仓库。
一、准备
- 一个可作为 Vuepress1 博客仓库的 GitHub 仓库（如
terwer/terwer.github.io）。 - 一个对该仓库有 push 权限 的 GitHub Token（PAT）（GitHub Settings → Developer settings → Personal access tokens，勾选
repo权限）。 - 该仓库是一个标准 Vuepress1 项目，文章放在
docs/目录，静态资源放在docs/.vuepress/public/。
二、配置
| 字段 | 填什么 |
|---|---|
| 首页地址 | GitHub 首页地址，默认 https://github.com |
| API 地址 | GitHub API 地址，默认 https://api.github.com，通常无需修改 |
| 用户名 | GitHub 用户名（owner），用于拼出仓库地址 |
| 鉴权 Token | GitHub 个人访问令牌（PAT），需对目标仓库有 push 权限 |
| git 仓库名 | Vuepress 博客仓库名，与用户名组成 <user>/<repo>，如 terwer/terwer.github.io |
| 默认分支 | 发布到的分支，默认 main，需与仓库实际分支一致 |
| 存储目录 | Vuepress 文章存储目录，默认 docs。发布后的 .md 写入该目录 |
| 文件规则 | 文章文件名规则，默认 [filename].md |
| 文章预览规则 | 站点文章预览规则，默认 /post/[postid].html |
| 预览规则 | GitHub blob 预览规则，默认 /[user]/[repo]/blob/[branch]/[docpath] |
| 图床 | Vuepress 支持内置图床，选「当前平台」：图片上传到仓库 docs/.vuepress/public/images（默认），文章中引用为绝对路径 /images/<图片名> |
三、图片与目录约定（Vuepress）
- Vuepress1 的文章来源目录是
docs/，文章.md写入该目录，文件名默认[filename].md。 - 图片选「当前平台」图床时，会提交到仓库根目录的
docs/.vuepress/public/images/，文章内引用为 绝对路径/images/<图片名>。 - Vuepress 构建时把
.vuepress/public目录映射到站点根，因此/images/...引用在构建产物中能正确显示。 - 文章 front matter 会写入的字段：
title、date、categories、article（标题含[日记]时为false），以及author（{ name, link }，取自配置的「作者」与「作者主页」，主页留空时用「平台首页 + 用户名」拼出）。开启「YAML 永久链接」且文章有别名时再写入permalink，取值固定为/post/<文章别名>.html（不读取「文章预览规则」）。「YAML 预设配置」留空则不额外补字段，填写时同名键会覆盖上述自动生成的值（含author）。
四、验证与发布
- 点「验证」→ Token、仓库、分支校验通过 → 保持「配置已保存并验证通过」。
- 快速发布 → 选 Vuepress → 发布。文章
.md会提交到存储目录/[filename].md。 - 点「查看文章」能打开仓库中该
.md的 blob 地址；带图发布时图片会一并上传到仓库docs/.vuepress/public/images并在文章中引用/images/<图片名>。
图片存储路径
图床选「当前平台」时，可以指定图片存到仓库哪里：
| 字段 | 默认值 |
|---|---|
| 图片存储目录 | docs/.vuepress/public/images |
| 图片访问链接 | images |
VuePress 的静态资源放在 .vuepress/public 下，构建后映射到站点根。一般不需要改，改了请保证两个值对应。
常见问题
- 验证通过但发布失败：确认 Token 对目标仓库有 push 权限，仓库名与分支正确，存储目录已存在。权限不足会收到 401/403。
- 图片要怎么发布：选「当前平台」图床，图片上传到仓库
docs/.vuepress/public/images，文章中引用绝对路径/images/<图片名>。构建时该目录映射到站点根，因此/images/...能正确显示。 - 查看链接打不开：查看链接默认是仓库 blob 地址（
/[user]/[repo]/blob/[branch]/[docpath]），仓库中存在该.md即可打开；若改为站点文章预览规则，需站点已部署且地址与规则一致。 - 发布后线上没有新文章：Vuepress1 是通过构建（
npm run docs:build）从docs/生成站点的，仅推送.md不会直接改变已部署站点；需配置自动构建（GitHub Actions / Pages / Vercel / Netlify 等）并触发一次构建。 - 更新与删除：点「更新」会重新提交并产生一次新提交；「删除」会从仓库移除对应
.md，需重新构建才能从站点移除。