@@ -10,10 +10,10 @@ tags:
1010- vitepress
1111- ci
1212created_at : ' 2026-03-26T00:00:00+00:00'
13- updated_at : ' 2026-03-26T17:07:07 +00:00'
14- submitted_at : ' 2026-03-26T17:07:07 +00:00'
13+ updated_at : ' 2026-03-26T17:08:56 +00:00'
14+ submitted_at : ' 2026-03-26T17:08:56 +00:00'
1515date : ' 2026-03-26'
16- word_count : 509
16+ word_count : 353
1717image_count : 0
1818type : guide
1919status : published
@@ -46,40 +46,15 @@ npm run docs:dev
4646
4747目标:将本项目的 VitePress Web 站点自动部署到 GitHub Pages。
4848
49- ### 1. VitePress base(默认无需配置)
50-
51- 本项目默认已自动处理 ` base ` ,包括 fork 场景在内,通常不需要手动配置:
52-
53- ``` ts
54- const repoName = process .env .GITHUB_REPOSITORY ?.split (' /' )[1 ]?.trim ()
55- const explicitBase = process .env .VITEPRESS_BASE ?.trim ()
56- const isGitHubActions = process .env .GITHUB_ACTIONS === ' true'
57- const isUserOrOrgSiteRepo = Boolean (repoName && repoName .toLowerCase ().endsWith (' .github.io' ))
58- const base = explicitBase
59- ? normalizeBasePath (explicitBase )
60- : isGitHubActions && repoName && ! isUserOrOrgSiteRepo
61- ? normalizeBasePath (repoName )
62- : ' /'
63- ```
64-
65- 默认行为:
66- 1 . 本地开发使用 ` base: '/' ` 。
67- 2 . GitHub Actions 构建项目页时自动使用 ` /<repo>/ ` (例如 ` /OpenKnowForge/ ` )。
68- 3 . 若仓库名是 ` xxx.github.io ` (用户/组织主页),自动使用 ` base: '/' ` 。
69-
70- 仅在特殊部署路径下需要手动覆盖:
71- 1 . 设置 ` VITEPRESS_BASE ` (例如 ` /docs/ ` 或 ` / ` )。
72- 2 . 如需覆盖 GitHub 社交链接,设置 ` VITEPRESS_GITHUB_REPO ` (` owner/repo ` 或完整 GitHub URL)。
73-
74- ### 2. 启用 GitHub Pages
49+ ### 1. 启用 GitHub Pages
7550
7651进入仓库:` Settings -> Pages `
7752
7853- Build and deployment -> Source 选择 ` GitHub Actions `
7954
8055这是必须步骤,否则工作流不会真正发布到 Pages。
8156
82- ### 3 . 触发部署
57+ ### 2 . 触发部署
8358
8459每次 ` commit ` 并推送到 ` main ` 后,GitHub Actions 会自动触发 Pages 部署。
8560
@@ -90,7 +65,7 @@ const base = explicitBase
90651 . 必做:在 ` Settings -> Pages ` 把 Source 设为 ` GitHub Actions ` 。
91662 . 必做:将代码推送到 ` main ` ,触发自动部署。
92673 . 可选:设置 ` VITEPRESS_GITHUB_REPO ` 指向你自己的仓库(如 ` your-name/your-repo ` )。
93- 4 . 通常不需要手改 ` base ` ;仅在特殊路径部署时才通过 ` VITEPRESS_BASE ` 覆盖 。
68+ 4 . 通常不需要额外配置;按默认工作流即可完成部署 。
9469
9570### Failed to load search index. Create notes via POST /note first.
9671
@@ -104,6 +79,6 @@ const base = explicitBase
10479
10580### GitHub Pages 页面样式异常或资源 404
10681
107- 1 . 优先检查 ` docs/.vitepress/config.ts ` 的 ` base ` 是否与仓库路径一致 。
108- 2 . 检查 ` Settings -> Pages -> Source ` 是否是 ` GitHub Actions ` 。
82+ 1 . 检查 ` Settings -> Pages -> Source ` 是否是 ` GitHub Actions ` 。
83+ 2 . 检查最近一次 ` Deploy VitePress to GitHub Pages ` 工作流是否成功 。
109843 . 等待 1~ 3 分钟后强制刷新页面,排除 CDN 缓存影响。
0 commit comments