秋水观 | Emanatism
Ektropia
2024-12-16
目录

本站开发日志原创

# 本站开发日志

来源：Tsuei.github.io开发日志 (opens new window)

我的第一个GitHub项目——VuePress式个人网站

标签：前端

# Chapter 1

# 前言

在网站的部署完成后，回头在开始补写一下做这个项目的动机吧。一是我发现许多程序员，都拥有自己的个人网站，作为博客文库，排版格式简明清晰，这使我本能地想拥有一个自己的网站，就像读书人维持自己的一份手稿那样；二是我对知识管理的急切渴求，网络时代信息爆炸，拥有自己的一套知识库就显得极其重要，况且我也是个爱杂学旁收的人。三是让我这个CS小白下决心莽撞一搏（被群友戏称为“大跃进”）的导火索，那就是某次在谷歌某个精神分析术语时，意外发现了一个上述形式的程序员小站 (opens new window)，上面堪称比我书架上任何一本纸质书都要容易查找，我思路瞬间打开，顿时觉得用网站收录知识实在重要。并且，就是顺着此站点对应的GitHub项目，发现其为一个名叫Vdoing的项目的克隆；而翻看Vdoing项目的指南（特别是“主题初衷与诞生”部分） (opens new window)令我十分受打动，让我觉得作者是个和我一样的人，使我得以下定决心。以下是原日志。

由于对大部分编程开发知识几乎是零基础等不可抗力因素，我抛弃了原有的自行建立一个VuePress项目的计划（开始于2024/12/16），即vuepress-starter文件夹。尽管我已经做了许多工作，使它的各方面完善起来，但纷至沓来的bug与我一点没有的开发底子，终于将我劝退。在对其的开发中，我造访了多个伟大项目的官网，通过文档了解到许多闻所未闻的东西，如Node、pnpm、Vue等，让我得以涉略到不曾了解，也必须去了解的一片广阔天地，并在这两天内灌注我以极大的信息量。这些，既是给一个尚未入门程序员的下马威，也能权当作无比宝贵的经验，因为在我学到相关知识后，我当会归来。

（在此，我将自建项目计划的日志也附上，是用文件夹命名写的：

在根目录中【作于12/16】：

  1. 我先安装了Node（也是放在D盘）为依赖环境。（参考Node.js文档 (opens new window)）
  2. 之后用PowerShell配置了包管理器pnpm。（参考pnpm文档 (opens new window)）
  3. 又在本目录用cmd安装了以Vue为框架的应用，即文件夹Ektropia Project。（参考Vue文档 (opens new window)）
  4. 继续用cmd创建了VuePress项目如下。（参考VuePress文档 (opens new window)）
  5. 尔来便可愉快地，开始使用VuePress了。
  6. 最后，记得常翻翻上述玩意的官网。

在vuepress-starter文件夹内：

  1. 提醒：这是一个VuePress项目。
  2. cmd须在此进行，因为这是.json的根目录。
  3. 一切照VuePress指南办，间杂GPT教导与谷歌。
  4. 运行了俩脚本，分别开发服务器、构建网站。
  5. 第二天【指12/17】配置，错愕发现VuePress没装，遂装如图。
  6. 随后发现装的是v1于是重装了v2。
  7. 随后创建配置文件。 【此后放弃】）

于是我回头转向那个名为VDoing的主题项目开始快速上手。“不建议在原默认vuepress项目上单独安装使用本主题包，而是clone我的整个项目再替换你自己的内容即可。”只得服从该建议了。多了一项目的：学习和使用该主题。

# 安装和启动

我采用“知识库兼博客风格预设配置”。

# 部署

安装、启动等出的问题都很容易解决，但是部署着实花了我不少时间。自此我开始维持本篇日志，因为我预感要完成它得走许多支路，需要反复试错，这是由于我遇到的许多问题，在文档的零星步骤中不曾被提及，我得在各处搜集解决方案。

最关键的一步，也是令我最难解决的是——一键部署的指令：

pnpm run deploy
1

的频繁失败。我试了几十次，实在是被苦苦折磨了。

心态波动和抗压能力不足，是这个项目开发的时间冗长的原因之一。有些开发细节记不清了，也是在所难免的。

为了能够顺利运行脚本，我安装了Git。其位置是：D:\Git

又在D:\Git\bin设置 Git 用户信息。

最后，一筹莫展的我决定听从GPT，使用SSH密钥来连。

生成的SSH密钥，我放在D:\KEY\id_rsa 里。

随后通过创建C:\Users\CZC.ssh/config 来指定密钥，其内容如下： Host github.com User git Hostname github.com IdentityFile D:/KEY/id_rsa

然而发现，无论怎么样，它都告诉我

D:\Ektropia-Project\Website-Stuff\vuepress-theme-vdoing>git push
ERROR: Permission to xugaoyi/vuepress-theme-vdoing.git denied to Tsuei.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

D:\Ektropia-Project\Website-Stuff\vuepress-theme-vdoing>
1
2
3
4
5
6
7
8

最后发现，SSH密钥是有了，但是SSH代理没启动。

在Git Bash 启动 SSH 代理：

eval $(ssh-agent -s)
1

返回进程 ID。

又在Windows 设置 > 应用 > 可选功能 添加了OpenSSH服务器。

然而，什么事也没发生。仍然是上述那样的情况。

# Chapter 2

# 1月21日

再次拾起本项目。重新审视这一切，最后翻阅文档的部署部分，才发现deploy.sh脚本内git push到的地址，得填写我自己的仓库呀（苦笑）。

还是对.sh文件所用的，好像叫shell语言中的bash，不熟悉---完全是未知的结果。这一行：

git push -f $push_addr HEAD:$push_branch
1

意即将本地Git仓库内容，推送到远程仓库。-f表强制推送；带号的两个，表示变量，分别为远程仓库的地址、远程分支，都是上文以去号的两个，表示变量，分别为远程仓库的地址、远程分支，都是上文以去后用=赋值过的。（全都是GPT教我的，嘿嘿）

遵从给出的格式改成了自己的仓库，试一回。 好像某次将npm也安装了，如今两者都能用。（npm文档 (opens new window)）

ssh: connect to host github.com port 22: Connection timed out
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
1
2
3
4
5

总算有些变化！不再告诉我权限之类的事了。看上去仅是网络问题之类的。

又发现，在GitHub仓库托管的deploy.sh脚本同我这里的有些许不同，这导致有一个地址仍是他的仓库。再次修改为我的。再试一回。

报错依然如上。但至少我们终于把目标给缩小了不是吗（笑）。我有一刻深信不疑是梯子不稳定的原因。谁让墙内连GitHub也不让登呢。

来简述一下问题吧，GPT君！：它的意思是SSH客户端无法连接到GitHub服务器。原因可能是网络问题，或防火墙设置。

GitHub的默认SSH端口为22。只要该端口被阻塞，SSH便连接不了GitHub。（正好最近在玩Hecknet，端口22都被我hack完了（（

我选择，先检测一下GitHub的端口22我到底是否能连。

机子上有Powershell，所以就用它来测试端口的连接。执行该行命令：

Test-NetConnection github.com -Port 22
1

# 1月22日

这天，梯子没有太大延迟，于是再试一次。而意外地，这一次的结果为：

Enumerating objects: 729, done.
Counting objects: 100% (729/729), done.
Delta compression using up to 32 threads
Compressing objects: 100% (495/495), done.
Writing objects: 100% (729/729), 6.68 MiB | 1.40 MiB/s, done.
Total 729 (delta 355), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (355/355), done.
remote: This repository moved. Please use the new location:
remote:   git@github.com:Tsuei/Tsuei.github.io.git
remote:
remote: Create a pull request for 'master' on GitHub by visiting:
remote:      https://github.com/Tsuei/Tsuei.github.io/pull/new/master
remote:
To github.com:tsuei/tsuei.github.io.git
 * [new branch]      master -> master
/d/Ektropia-Project/Website-Stuff/vuepress-theme-vdoing
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

我……没有看错吧。这好像，是成功了耶。意思是成功了吗？ 我点开了链接，原来列出了命令对仓库做出的所有的改动，所谓Comparing changes。它们全部位于一个名为master的分支Branch下。

不错，我适才方知道GitHub仓库中分支的概念。而早已有的main分支，是我创建这个仓库，默认一开始就有的，只有一个README文件。

将结果交给GPT看看。 “是的，成功了！你成功地将更改推送到了新的远程仓库。……”

赶快看看文档，下一步是什么？我已经等不及我的网站上线了。

“好耶！终于成功了。是的，我确实是在部署我的网站。下一步，应该怎么做？是要“设置仓库的GitHub Pages”吗？” “恭喜你成功推送了代码！🎉 现在是时候完成 GitHub Pages 的设置，让你的网站上线了。以下是详细的步骤：……” 于是，比起文档上孤零零的一句话，我开始按GPT列出的详尽步骤一一完成。

打开仓库，进入设置Setting，选中Code and automation里的Pages， 在一级标题Build and deployment下，它告诉道“Your site is live at https://tsuei.github.io/ Last deployed by @Tsuei last month”，是我初立项目的时候。 在二级标题Source里，确认部署是使用分支的； 在二级标题Branch里，它提醒道“Your GitHub Pages site is currently being built from the main branch.” 将默认使用的main分支，改为刚使用命令推送上去的master分支。难怪tsuei.github.io一直都是两行，原来那是main分支默认的README。分支和网站的映射关系，这就搞清楚了。 按下Save。“GitHub Pages saved.” 接下来，只是片刻等待。Pending后，等待checks的completed即可。有两个在数秒内就successful了，而另一个仍在in progress。在仓库的master分支页面，以及Action里，全部有进度的可视化。 Success。成了。我成功了。 打开tsuei.github.io。刷新。即得到了熟悉的模板界面。 可以看到，作为一个知识库，它首先拥有文档和博客两大板块，这也是我之所以会相中Vdoing项目；而细分之类，则不可举数。 是的，万事业已俱备。现在只需要对文字简单地改动后，属于我的知识库便会到来。可想在今后的时日里，首先要将一系列文档转移到其上；或者先以一个任务完成者的姿态，回头审视一遍一路走来的各种历险，重新翻阅各种文档，必然会有新的体会。但那些都是后话了。作为一个连Git都不知道是啥的纯纯新手，终于完成个人网站的建立，也算做好了第一个GitHub项目。这固然是一名新程序员、一名大一CSer迈出的第一步、起手式，但这世上还有比做好自己致力于完成的事情更令人快乐的吗？

部署完成于2025/1/22/18:58。随后给此日志添加了标题和前言。

# 修改

但也只是迈出了第一个步子：把项目clone下来了。 在我更改前，tsuei.github.io同项目给出的案例1，xugaoyi.com是一模一样的。Vdoing主题的知识库兼博客站。 接下来就需要在此基础上，替换我自己的东西。而替换是一种修改。

首先，确定在哪里更改：或许只能在本地文件夹更改，因为仓库里似乎并没有docs文件夹，master仅仅托管的是静态文件。 注意：脚本通过git，在仓库里推送的master分支内，仅仅是用来维护网站的静态文件， 是通过脚本构建的docs/.vuepress/dist内的内容，即静态站点文件。 它们被脚本中的npm run build:win命令构建，直接供 GitHub Pages 部署和展示网站使用。在完全写入仓库的master分支后，在本地删除。 如果需要协作开发，可将脚本已经部署的master更名为gh-pages，使master存储源代码。 其次，更改过程中，应该挂着原Vdoing仓库的对应原代码，这样便于有改动使出现bug时的复原。挂着项目文档以查阅指南。挂着GPT以随时询问。 主题项目内写了比较多的注释代码，很方便我的学习和使用，甚至连markdown、yaml、ts、json语法都无需掌握。

再次，弄清哪些是需要修改的： 问：clone 项目后需要修改哪些地方？ 答：大致的修改流程是这样的： 首先让项目正常的跑起来 （√） 根据需求构建和替换 docs/<结构化目录> 的目录及内容 根据需求修改 config.js 配置 （√） 修改 首页配置 （√） 修改 主题颜色和样式（如果你想修改的话）

最后，怎么将修改传达到网页上？ 在每次更改后，需运行git指令，以推送给仓库，进而让Page更新； 但由于我没学Git，就只能仍然使用部署指令npm run deploy，勉强达到完成更新的效果。 这样做只会带来一个坏处——那就是查不到往期版本，重新部署会覆盖原来的一切，包括原来部署的记录。 所以说，Git的本质是版本控制器，此言不虚。

所以，就在此简单记录修改：1/26,27,30.

# Chapter 3 3/22

3/21即前一天，我决定重启该个人站，第一件事就是要把线上编辑给做出来，却因为不熟练git操作意外将除新增文件以外的文件全部删掉了。 这意味着我要重新开始。 顺便将本日志从.txt改为.md继续记录。

# 部署（再一次）

# 第一个问题

linux换行变成Windows 风格的换行符 (\r\n)，而 Linux 环境下需要 Unix 风格的换行符 (\n) 可以用 dos2unix 工具将换行符转换为 Unix 格式： dos2unix deploy.sh

# 第二个问题

VuePress 依赖的 esbuild 缺少 Linux 64 位系统的二进制包（esbuild-linux-64） 安装即可。注意要退版本，不能用最新的；不用旧版本就得一句一句改。

# 第三个问题

是有关配置文件的事，.ts不能与部署脚本有很好的契合，连连报错。 共有三个：config.ts、baidu.ts、xxx.ts。 该问题上次我亦遇到。不知怎么clone下来的都是.ts，而本尊的GitHub仓库都是.js。 从那里上抄来相应的.js文件，前缀加.以隐藏.ts文件即可。 使用文件优先级：.ts>.js。

# 第四个问题

该脚本需要在bash命令窗运行，而WSL能做到这点。就是说所有指令前须均加上wsl，或者直接wsl进入wsl先。 就因为这个，上次在windows下好的诸环境全都不起作用了。 wsl上要安装自己的环境依赖。花了我不少时间，也用npm下了不少东西。

# 第五个问题

因此，在最后的git push上仍有上次一样的网络问题。 首先把origin的html url换成ssr url。 我已轻车熟路，配置好.ssr文件即可。配置文件须加上端口22. 测试连接上后，推送成功即可。

# 实现在线编辑（自动集成，无需再本地运行脚本）

参考：Chat-GPT、DeepSeek：https://chat.deepseek.com/a/chat/s/a2efa464-72ec-4c9e-a669-4f7f418514c8

https://doc.xugaoyi.com/pages/0fc1d2/#_2-使用github-action自动持续集成、

https://xugaoyi.com/pages/6b9d359ec5aa5019/。 部署完成后，我改变以往的一改一部署，直接使用GitHub Actions实现线上编辑。（也是我昨晚预计做却误删工程的）

# 第一步即提交源代码到远程仓库

master分支已被旧构建文件用了，有些舍不得删；决定投到main分支。 很轻松就投送完成。 接下来，新建目录与文件./.github/workflow/build.yml (.yml即可，名字随意)

# 第二步配置该文件build.yml

该文件的功能是作为仓库的GitHub Actions下的一道工作流，使用在线虚拟机。 本地部署在wsl运行，而线上自动部署是在虚拟机上（ubuntu-latest）。 保险起见，我在本地写好，然后推送给远程。

# 第三步静候佳音

投送后，该文件便开始工作，其流程与漫长的工作时间与部署别无二致，并宣告了deploy.sh的退休。 初次部署后，修改config.js来测试。测试结果说明，它的确做到了良好的在线编辑，该项目长久以来的夙愿至此实现。 对工作时间进行优化，我添加了缓存依赖。但没有好的成效。

# 博客站工作，与闲聊

首先，像上次那样将主页index.md和站点UI配置config.ts改改，换成自己的东西。 不过，得益于这回实现了在线集成，这项工作显得十分丝滑与优雅——这亦是我所追求的。

#

在线集成以外，这次工作的最大得力助手便是VS Code和Git了。 上次我的主要开发平台还是VS 2022，而只把VS Code当作记事本用。是在本学期以来，我才意识到它强大的功能。 就是这种功能的强大为我的工作学习带来了不可思议的便利。可以说，在会用VS Code之前，我压根不会编程， 例如，在如浏览器一般简洁的界面上，VS Code内置的文件资源管理器使文件在哪变得一目了然、直观明晰。尤其是一个个.md文件列出有如目录一般。 它让你知道你在做什么，以及将做什么。

#

前几天，我完成了第二个项目voidinput（如果把本项目称作第一个的话），并借着势头用git顺利推送到远程仓库，学了些git皮毛。 然后就有我的盲目自信用git把本项目的旧版本删的一干二净了（笑）（只有新建文件如我自行替换的背景图标图片残存） 也是因祸得福吧。没有绝对的痛楚与绝望，我也不至于在一天之内就完成工作，还完成得比旧版本完成所用的一两个月要好。（笑） 这就是辩证法。

#

回归正题。博客站的UI方面（形式）完善好后，文章（内容）就要开始整理上传了。 我文章多了去，不过多数是在OneNote和Word上写的，可以说比较散乱。因此需要整理，再又要翻译成Markdown语法。 （做笔记开始用Markdown亦是我不久前的事，主要是懒得排版。有它再配上好用的VS Code后，我以为什么笔记软件都不过语法糖罢了。） （笔记不重要，而是输出这件事本身。——我曾这样总结道。Markdown之所以做到排版出色，是因为它是为消灭排版的目的而设计的。——我又曾这样总结道。） 有.md文件后，提交commit、推送push也就不是什么大事了，命令行不熟有VS Code的图形化；部署则更不是什么大事了，有Actions的自动集成。 于是，面对我们这个得到了有条不紊的大一统的体系，谁人能不欣慰而面喜？ 每一次提交我都会在消息详细说明，因此本日志上小的改动不会细说。 （话说，某次乱用git导致多了一堆贡献者，目前不知道怎么删😓4/2向GitHub官方提交表单(Ticket)后已解决😉）

# New Chapter 3/23

# 展望

至此，本项目取得阶段性成果。但面对暂时的成果，我们必摇摇头否定道：“不是这个！”。 I create(/labour?) therefore I am. 扬弃的过程，就是事物自己否定自己而转向一个他者，并在那里发现他者于自己的同一后返回自身。 出于这样的思维规律，为本项目列出以下的todolist：

  1. 买域名并配上。GitHub Pages默认的.github.io太显眼，有损逼格。
  2. 博客站归根结底是发布的媒介。而我有着大量的文稿。第一步就是把他们整理成.md文件。
  3. 多学习前端与互联网相关（例如html协议、ssh协议到底是啥）。 本项目是我在初生牛犊的时代靠蛮力吃下的。因此，无数踩到的坑给予了我海量的经验与教训，也拿走了我不少头发。 博客站我们能做，而且能做好；而前端可不止一个博客站。 再一次搞清楚本项目的定位吧：它是基于Vue和VuePress实现的静态站点（用来存放文档作博客最合适不过），依赖npm、Nodejs等等（这方面，看文首），经由GitHub部署。 假以时日，我们能像那些大佬作一本线上书籍也说不定。

# 待更

我发现，之所以画大饼是必要的，是因为在每个阶段性胜利后总有着所谓“告一段落”，也就是兴趣会转向其它项目。 本项目即搭建个人站点，属于前端，又属于Web大类。 而整个CS方面繁泛，我现在就想去看看Linux、CTF（属于信安）、算法（指竞赛性的XCPC一类）和AI（机器学习）。 后会有期。并整理好一开始只是为提醒自己少踩点坑为目的本日志，分章分节发表，以飨来者。

（其实并没有，这几天除了课业就是放送、编辑网站文章，或者修改排版，看看commit就知道了）

# 修订记录与Tips

# 修订记录

4/2/20:48。

# 放送/新建文章步骤（不分先后）：

  • 修改配置文件config.js，以使能在最上栏找到访问入口；
  • 目录页.md无需修改；
  • 在对应类属目录中新建文章本身.md文件，除文章主体外在开头增加必要说明。

# 使网站支持显示LaTeX公式 4/4

4/1，我提出这几个待做项：

  1. 清除贡献者；
  2. 修订日志
  3. 安装latex插件；

4/2，前两项很顺利地完成了。今天来做第三项，却有些问题。

# 1、下载KaTeX插件

有两种插件，更早的是Mathjax。我追求轻量而选择KaTeX。 在bash终端里运行

npm install -D vuepress-plugin-katex
1

以下载KaTeX插件。随后在config.js里添加plugin相关信息。 然而没用。

# 2、配置是否有误？

在config.js里添加了math:true。然而也没用。

一番周折才发现，有几个可能原因：

  1. GitHub Pages的Markdown渲染器不支持数学公式。因此，需要插入html或者在config.js的head里添加强制渲染的信息。但是这解释不通为什么其它基于GitHub源代码的网站能显示公式。我本来想用F12即时调试一下，但编辑不了作罢。
  2. 我的LaTeX语法有误。

# 3、借鉴开源代码

去查看Oi.wiki的复杂度 (opens new window)页的源代码，发现它仓库中的Preview能显示公式，而我的Preview却不行。这就是差异。于是我查看Code后发现，他的公式都是用形如

∀xΦ(x) \forall x \Phi(x)

包裹的，而我则是

[ \forall x \Phi(x) ]

尽管两者在一般情况下都合法，但只有他的在GitHub中成功渲染了。莫非就像这样单纯是语法问题？ 我将[]全部改成$$试试。

但是我这边也有个Preview (opens new window)是Preview能显示而网站页面不显示的，很奇怪，但这是个突破口。

# 4、引入CDN

通过按F12查看HTML代码，我发现OI wiki的做法是引入CDN，其实就是在html的head部加上几个与katex有关的网站。 那么我也来试一下。修改config.js中head部分来引入KaTeX的CDN。

问到这里，GPT等AI就开始绕圈子或者旁逸斜出了。血的教训，事实证明AI不能依赖过多的。否则你就会像我一样，一天搞不定一个BUG。

# 转向博客搜索

官网给出的markdown-math (opens new window)仅支持VuePress 2.0版。 遂转向博客推荐的markdown-it-texmath。相关文章发布文章是2022年左右，和我所用主题创建的年份差不多。 原来装的KaTeX就不管了。

npm i markdown-it-texmath
1

参考：https://blog.csdn.net/m0_50488756/article/details/123799709

# 调试方法 4/5

学会一个新调试（debug）方法，直接用

npm run dev:win
1

来本地将网站构建（build）到localhost808X，查看没什么问题就可以提交（commit）了，避免出现昨天一天17个提交的情况（笑）。

# 目录显示几级标题 4/5

因AI踩了一些坑，修改themeConfig块内的sidebarDepth，但是没用；

后来发现我有误解，toc指的就是配置目录（Table of Contents），即

要改侧边栏得像.ts里写的那样改extractHeaders。。

我翻阅了VuePress和Vdoing主题https://doc.xugaoyi.com/pages/8dfab5/#markdown-extractheaders 官方文档，问题迎刃而解。

根据这段时间的经验，获取信息可靠度：文档>博客>AI文档>博客>AI。AI一定是最后上场。

总结一下，今天 1、重启了标题锚点， 2、对于一些文章，用命令[[toc]]在正文插入目录块，能从一级标题列到六级标题， 3、目录栏一开始只能显示二三级标题，到现在能一直显示到六级标题。

列一下待做项：

如何让你的笔记更有表现力 (opens new window)

# 置顶与摘要 4/8

# 置顶

使用

sticky: 1
1

其中数值越大优先级越高。

# 添加摘要

首先在index.md中保证

postList: detailed
1

详见：https://doc.xugaoyi.com/pages/1cc523/

编辑 (opens new window)
上次更新: 2025/04/23, 14:00:51
Linux学习参考

Linux学习参考→

最近更新
01
绝对唯心论 原创
03-30
02
经济学草稿 原创
03-29
03
精神分析笔记 原创
03-29
更多文章>
Theme by Vdoing | Copyright © 2024-2025 Ektropia Tsuei | MIT License