xszn.github.io 行书指南

行书指南

行书指南

行书指南是一个自由及开放源代码（FOSS）的软件列表项目，推荐高质量免费与开源软件，降低用户寻找软件的时间成本。

:information_source: 关于项目

如何挑选一款软件

  • 免费。专有软件无定价和付费版
  • 开源。项目维护积极和具有现代化 UI
  • 趋势。搜索指数攀升和仓库 Stars 数
  • 影响。网站访问量和周边生态丰富
  • 易用。开箱即用，无需配置

这些都是综合考虑因素。

适用于谁

本项目适用于 Windows、Android 和 Chromium 的用户。

:package: 安装

1. 前置准备

Node.js 18 及以上版本。

2. 克隆项目

1
git clone git@github.com:xszn/xszn.github.io.git

3. 安装依赖

1
npm i

4. 启动并运行

1
npm run dev

:handshake: 如何贡献

欢迎你的引荐，或向我们提问。

:scroll: 许可

已获 CC BY-NC-ND 4.0 许可    

:chart_with_upwards_trend: Star History

Star History Chart

我的搭建过程

完整操作步骤（从当前已克隆的目录开始）

步骤 1：进入本地克隆的仓库目录

如果还没进入，执行以下命令：

1
cd xszn.github.io

步骤 2：安装项目依赖（构建前的必要准备）

1
npm install
  • 执行后会生成 node_modules 文件夹，安装所有 VitePress 相关依赖
  • 出现的 npm audit 漏洞提示无需处理，不影响构建和部署

步骤 3：本地构建 VitePress 静态文件

该仓库的构建脚本是 build，直接执行：

1
npm run build
  • 构建成功后，会在 ./.vitepress/ 目录下生成 dist 文件夹（核心静态文件目录，包含 HTML/CSS/JS，可直接部署）
  • 构建过程中无红色报错即成功，少量黄色警告可忽略

步骤 4：进入构建后的 dist 静态文件目录

1
cd ./.vitepress/dist

步骤 5：初始化 Git 仓库（dist 目录无现成 Git 配置）

1
git init

步骤 6：添加并提交所有静态文件（必须填写非空备注，避免空提交错误）

1
2
3
4
5
# 1. 添加所有静态文件到暂存区
git add .

# 2. 提交文件，备注清晰便于追溯
git commit -m "构建 VitePress 静态文件，用于部署到 GitHub Pages gh-pages 分支"
  • 提交成功后，终端会显示文件变更记录，说明本地有了有效提交记录

步骤 7：关联你自己 fork 的 xszn 仓库（不要关联原仓库）

1
git remote add origin https://github.com/Zhang-Curry/xszn.git
  • 若提示「remote origin already exists」，说明已关联过，直接跳过该步骤

步骤 8：将本地分支重命名为 gh-pages（GitHub Pages 专用部署分支）

1
git branch -M gh-pages

步骤 9：强制推送到你 fork 的 xszn 仓库的 gh-pages 分支

1
git push -u origin gh-pages --force
  • --force 是安全的（首次推送无历史冲突，确保静态文件完整上传）
  • 推送成功后，终端会显示 gh-pages -> gh-pages，说明远程分支已创建并同步

步骤 10：网页端配置 GitHub Pages（收尾，让博客可访问）

  1. 打开你 fork 的 xszn 仓库：https://github.com/Zhang-Curry/xszn
  2. 点击顶部「Settings」→ 左侧导航栏「Pages」
  3. 在「Build and deployment」区域：
    • 「Source」选择「Deploy from a branch」
    • 「Branch」下拉框选择 gh-pages，目录保持 /(root)
    • 点击「Save」保存配置

步骤 11：验证访问结果

  1. 保存后等待 5-10 分钟，让配置生效
  2. 浏览器访问地址：https://zhang-curry.github.io/xszn/
  3. 能正常展示 VitePress 博客页面（而非 README）即部署成功

补充说明

  1. 后续更新博客的简化流程（修改内容后）：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    # 1. 回到 xszn.github.io 目录
    cd ../../..

    # 2. 修改 docs 下的 md 文章或配置
    # 3. 重新构建
    npm run build

    # 4. 进入 dist 目录提交并推送
    cd ./.vitepress/dist
    git add .
    git commit -m "更新 VitePress 博客内容"
    git push origin gh-pages --force

  2. 不要推送到原仓库：你没有 xszn/xszn.github.io 的写入权限，只能推送到自己 fork 的仓库

  3. gh-pages 分支的作用：专门存放静态部署文件，与 main 分支的源码分离，便于管理

总结

  1. 核心流程：安装依赖 → 构建静态文件 → 推送 dist 到自己仓库的 gh-pages 分支 → 配置 Pages；
  2. 关键要点：始终推送到自己的 fork 仓库，部署分支固定为 gh-pages，提交必须填写非空备注；
  3. 验证标准：访问默认地址能展示 VitePress 博客，而非 README 页面。

按这个流程操作，就能顺利完成本地构建与远程部署，你的 fork 仓库博客就能正常访问啦！

Q：gh-pages是什么意思？

gh-pages 是 GitHub 官方推荐的「静态站点部署分支」，专门用于存放静态部署文件，核心优势有 3 点：

  1. 职责分离，清晰整洁

    • main 分支：只存放源码，专注于「内容创作和配置修改」；
    • gh-pages 分支：只存放静态部署文件，专注于「博客展示」；
    • 两者互不干扰，提交历史清晰，后续维护、回滚、同步原仓库更新都非常方便。

  2. 符合 GitHub Pages 约定，配置简单

    • GitHub 对 gh-pages 分支有「特殊优化」，配置 Pages 时，gh-pages 会优先出现在分支下拉框中，无需额外查找；
    • 很多静态站点生成器（VitePress、Hexo、Hugo）都默认支持自动推送到 gh-pages 分支，后续如果配置自动部署（GitHub Actions），可以直接复用现成的脚本，无需修改。

  3. 无权限风险，不影响源码分支

    • 即使 gh-pages 分支出现问题（比如静态文件推送错误），也不会影响 main 分支的源码，只需重新构建推送 gh-pages 即可，不会造成不可挽回的损失。

补充：如果非要推送到 main 分支，该怎么操作？（不推荐，仅作了解）

如果你只是想尝试，步骤如下（仅修改推送相关步骤）：

  1. 完成「本地构建」→ 进入 ./.vitepress/dist 目录 → 初始化 Git → 添加并提交文件；

  2. 关联你 fork 的 xszn 仓库：

    1
    git remote add origin https://github.com/Zhang-Curry/xszn.git

  3. 直接推送到 main 分支（强制推送，会覆盖 main 分支原有源码）：

    1
    git push -u origin main --force

  4. 网页端配置 GitHub Pages：从 main 分支部署，保存生效。

⚠️ 警告：该操作会完全覆盖你 fork 的 xszn 仓库 main 分支的所有源码，后续无法再方便地修改博客内容，谨慎操作！

总结

  1. 「重命名为 gh-pages」不是语法必须，但是 GitHub Pages 部署的最佳实践，核心是分离源码与部署文件；
  2. 不推荐推送到 main 分支，会污染源码、增加维护成本，不符合最佳实践；
  3. 核心要点：gh-pages 专门用于部署，main 专门用于存放源码，两者分离是静态站点维护的「黄金法则」。

操作过程代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry
$ git clone https://github.com/xszn/xszn.github.io.git
Cloning into 'xszn.github.io'...
remote: Enumerating objects: 1821, done.
remote: Counting objects: 100% (252/252), done.
remote: Compressing objects: 100% (190/190), done.
remote: Total 1821 (delta 118), reused 145 (delta 61), pack-reused 1569 (from 2
Receiving objects: 100% (1821/1821), 13.34 MiB | 143.00 KiB/s, done.
Resolving deltas: 100% (807/807), done.

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry
$ cd xszn.github.io/

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io (main)
$ npm i

added 192 packages, and audited 193 packages in 6s

54 packages are looking for funding
  run `npm fund` for details

6 vulnerabilities (4 moderate, 2 high)

To address all issues, run:
  npm audit fix

Run `npm audit` for details.

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io (main)
$ npm run build

> build
> vitepress build


  vitepress v1.6.3

✓ building client + server bundles...
✓ rendering pages...
✓ generating sitemap...
build complete in 7.77s.

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io (main)
$ cd ./.vitepress/dist

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io/.vitepress/dist (main)
$ git init
Initialized empty Git repository in E:/Blog/ZhangCurry/xszn.github.io/.vitepress
/dist/.git/

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io/.vitepress/dist (master)
$ git add .

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io/.vitepress/dist (master)
$ git commit -m "构建 VitePress 静态文件，用于部署到 GitHub Pages gh-pages 分支"[master (root-commit) 837f2b7] 构建 VitePress 静态文件，用于部署到 GitHub Pages
gh-pages 分支
 514 files changed, 5080 insertions(+)
 create mode 100644 .nojekyll
 create mode 100644 404.html
 create mode 100644 CNAME
 create mode 100644 about-us.html
 create mode 100644 ads.txt
 create mode 100644 assets/about-us.md.C1m4Rd6r.js
 create mode 100644 assets/about-us.md.C1m4Rd6r.lean.js
 create mode 100644 assets/app.Cd-yBXLJ.js
 create mode 100644 assets/audio-software_aimp.md.BlBKLDDd.js
 create mode 100644 assets/audio-software_aimp.md.BlBKLDDd.lean.js
 
......

 create mode 100644 network-software/localsend.html
 create mode 100644 network-software/page-assist.html
Enumerating objects: 610, done.
Counting objects: 100% (610/610), done.
Delta compression using up to 16 threads
Compressing objects: 100% (607/607), done.
Writing objects: 100% (610/610), 6.73 MiB | 25.61 MiB/s, done.
Total 610 (delta 140), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (140/140), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/Zhang-Curry/xszn/pull/new/gh-pages
remote:
To https://github.com/Zhang-Curry/xszn.git
 * [new branch]      gh-pages -> gh-pages
branch 'gh-pages' set up to track 'origin/gh-pages'.

Curry@DESKTOP-P743UFE MINGW64 /e/Blog/ZhangCurry/xszn.github.io/.vitepress/dist (gh-pages)
$