一、状态

重装系统意味着系统盘上的工具链全部消失,但只要博客源码目录放在非系统盘,内容与版本历史就仍然完整。接手时先做资产盘点,再决定动作。

项目状态
仓库路径C:\SpaceFloder\HugoBlog\CodingBlog\my-blog
原路径(历史记录中的)C:\Users\sinho\Desktop\CodingBlog\my-blog
远程仓库github.com/Sinhoole/sinhoole.github.io
分支main,与 origin/main 同点
仓库 HEAD5964d8b
.git 对象库完整(含 pack、index、refs)
Git未安装
Hugo未安装
Node / pnpm未安装

结论先行:数据无损,缺的只是"能跑起来"的工具。因此本次工作的重点是恢复工具链、恢复认证、修正因目录迁移而失效的路径,并重新建立可一键执行的脚本。

二、环境勘查

先确认"缺什么",再决定"装什么"。检查分三类。

2.1 命令可用性

逐个探测 hugo、git、node、npm、pnpm、winget、scoop、choco、go、python。

结果:hugo、git、node、npm、pnpm、scoop、choco、go 均不存在;python 是 Microsoft Store 的占位程序;winget 存在但不可用,执行 winget --version 返回 0x8A150001,无法承担安装任务。

2.2 全盘检索既有二进制

在 C:\DATA、C:\SpaceFloder、C:\Program Files、%LOCALAPPDATA% 四个常见根目录做四级深度检索,查找 git.exe 与 hugo.exe,结果为空。排除了"已安装但未加入 PATH"的可能,确认必须重新安装。

2.3 仓库内部状态

读取 .git/config、.git/HEAD、.git/refs、.git/objects,确认分支与历史完整;同时确认旧配置里保留了两条重要信息:一是本地提交身份(sinhoole / [email protected]),二是为 https://github.com 设置的 SOCKS5 代理 socks5://127.0.0.1:7897。

此外通读了仓库内的 .workbuddy/memory/ 六份记忆与 project-summary.md,用以复原此前的技术约定,避免"重新发明"配置:

  • 主题为 PaperMod,永久链接为 blog = '/p/:contentbasename/';
  • 评论系统为 Twikoo(envId = https://twikoo.taoxi.ink);
  • 字体为本地 LXGWBright(static/fonts/LXGWBright-Regular.woff2),由 assets/css/extended/custom.css 以 @font-face 加载;
  • 数学公式通过 Goldmark passthrough 与 KaTeX 渲染;
  • 文章命名早期为纯数字(YYYYMMDD、YYYYMMDD-NN)。

三、网络诊断

本次共出现两次网络相关的误判,均为"现象相似、根因不同",值得单独记录。

3.1 第一次误判:把执行环境的限制当成线路封锁

在受限 shell 中访问任意 HTTPS 站点(包括国内可达站点)均报同一错误:

curl: (35) schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS (0x8009030e)

若真是线路封锁,不可能对全部域名返回完全相同的错误,且错误发生在 TLS 握手开始之前的凭据获取阶段。据此判断:问题在 TLS 栈的凭据获取,属于执行环境限制,而非网络。

验证方式有两条:其一,改用宿主侧请求工具访问 https://github.com,得到 HTTP 200;其二,在放宽限制的 shell 中直连下载安装包,速度正常。由此确认 GitHub 可直连,下载不需要代理。

3.2 第二次误判:系统代理指向未启动的客户端

注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings 中 ProxyEnable = 1、ProxyServer = 127.0.0.1:7897,但 7897 端口无监听进程。这说明代理软件(Clash Verge)已退出,而系统代理开关仍停留在开启状态。

影响:所有遵循系统代理的程序(浏览器、Invoke-WebRequest 等)会连接一个不存在的端口而失败。处置:以 --noproxy '*' 绕过系统代理完成下载;同时删除 Git 中遗留的 http.https://github.com.proxy,避免"未启动代理就推不上去"的隐性依赖。

3.3 第三次现象:TUN 模式导致 SSH 无法建立

后续在推送阶段出现:

ssh: Connection closed by 198.18.0.26 port 443

198.18.0.0/16 是 Clash 的 fake-ip 段。开启"虚拟网卡(TUN)“模式后,DNS 会把所有域名解析到该段,由代理内核接管流量;而 SSH 客户端不遵循系统代理,连接被直接关闭。关闭 TUN 后,github.com 立即恢复解析为真实地址(20.205.243.166),推送恢复正常。

这一条已固化进部署脚本:推送前若发现解析结果落在 198.18.0.0/16,脚本会主动提示关闭 TUN 模式。

四、安装 Git 与 Hugo

4.1 版本选择

Hugo 固定为 v0.162.1 extended,理由不是"稳定”,而是与线上一致:vercel.json 中写死了 HUGO_VERSION = 0.162.1,本地若用别的版本,构建产物可能与线上不同,排查问题时会产生噪音。当时最新版已是 v0.168.0,本次刻意不升级。

Git 取当时的稳定版 2.56.0.3(Git for Windows)。

4.2 下载

在放宽限制的 shell 中执行 curl -L 直连下载,不经过代理:

文件大小
Git-2.56.0.3-64-bit.exe63.7 MB
hugo_extended_0.162.1_windows-amd64.zip21.4 MB

4.3 安装

Git 使用 Inno Setup 的静默参数,以 -Verb RunAs 触发 UAC,由用户在弹窗确认:

Start-Process -FilePath $gitExe -Verb RunAs -Wait `
  -ArgumentList '/VERYSILENT','/NORESTART','/SP-','/NOCANCEL'

安装目录为 C:\Program Files\Git,安装器同时写入机器级 PATH。

Hugo 官方只提供压缩包,没有安装程序。解压至 C:\DATA\Tools\hugo,得到单一可执行文件 hugo.exe(约 62 MB)。

随后把两个目录追加到用户级 PATH:

C:\Program Files\Git\cmd
C:\DATA\Tools\hugo

验证结果:

git version 2.56.0.windows.3
hugo v0.162.1-bba860e3eda3091efe8c6d1a96bc49a29ad2d5f6+extended windows/amd64

4.4 关于 Node

本站构建不需要 Node。PaperMod 没有 package.json,样式与脚本由 Hugo extended 内置的管道处理(主题的 head.html 使用 resources.Get | js.Build,即内置 esbuild)。因此未安装 Node 与 pnpm,避免引入无用依赖。

五、Git 身份与远程

重装后全局配置丢失,仅仓库内的本地配置仍在。补齐全局配置如下:

配置项取值理由
user.namesinhoole与历史提交者一致,避免提交身份混杂
user.email[email protected]同上
init.defaultBranchmain与远程默认分支一致
core.autocrlffalse仓库文件均为 LF,关闭自动转换以避免整文件 diff
core.quotepathfalse中文路径在 git status 中正常显示
pull.rebasefalse默认合并策略,减少误操作
push.defaultsimple仅推送当前分支到同名远程分支
credential.helpermanager保留 HTTPS 通道的凭据能力,作为兜底

远程地址由 HTTPS 切换为 SSH:

git remote set-url origin [email protected]:Sinhoole/sinhoole.github.io.git

六、SSH 密钥与认证

6.1 生成密钥

使用系统自带 OpenSSH(C:\Windows\System32\OpenSSH\ssh-keygen.exe)生成 ed25519 密钥对:

私钥  C:\Users\sinho\.ssh\id_ed25519
公钥  C:\Users\sinho\.ssh\id_ed25519.pub
指纹  SHA256:RXec6iNOpSiHPFsq6P6XDR79x+4WFx4ygEuron5hMZU

未设置口令,目的是让双击脚本可以无交互完成推送;代价是私钥以明文形式存在于用户目录,安全性依赖系统账户本身。若后续有更高要求,应改为带口令并配合 ssh-agent。

6.2 客户端配置

在 ~/.ssh/config 中固定走 443 端口:

Host github.com
    HostName ssh.github.com
    Port 443
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

ssh.github.com:443 与 github.com:22 提供相同服务,但在受限网络中更容易连通,因此作为默认配置写入。

6.3 授权与验证

公钥由用户在 GitHub 的 Settings → SSH and GPG keys 中添加。验证命令:

成功返回:

Hi Sinhoole! You've successfully authenticated, but GitHub does not provide shell access.

补充说明:添加公钥之前首次测试返回 Permission denied (publickey)。这个错误恰好说明传输层已连通、仅缺授权,因此可以断定问题不在网络,而在密钥注册。区分"连不上"与"没授权"是排查此类问题的关键一步。

七、清理失效配置

7.1 .gitmodules 是无效声明

仓库根目录存在 .gitmodules,声明子模块 hugo-PaperMod,路径为 hugo-PaperMod。但事实是:

  • git ls-files -s 中不存在任何 mode 160000 条目;
  • themes/PaperMod 下的 126 个文件全部以普通文件(mode 100644)入库。

也就是说,主题是以"vendored"方式并入主仓库的,子模块从未真正启用。保留 .gitmodules 会让 git submodule 系列命令指向一个不存在的路径,属于会误导后续维护的残留。处置:删除 .gitmodules,并移除 .git/config 中对应的 submodule.* 段。

需要指出的是,themes/PaperMod/.git 仍指向 .git/modules/hugo-PaperMod,这是历史遗留;由于索引中没有 gitlink,它不影响构建,也不影响提交。本次未做删除,避免无谓风险。

7.2 删除隐性的代理依赖

删除 .git/config 中的 http.https://github.com.proxy = socks5://127.0.0.1:7897。理由见 3.2:该配置会让 Git 在代理未启动时直接失败,而实测直连可用,属于负资产。

八、构建与本地验证

工具装好之后,先验证"能构建",再验证"能推送",顺序不可颠倒。

8.1 生产构建

hugo --gc --minify

结果:378 个页面、198 个别名页,输出约 580 个文件、约 10 MB,无任何警告。这一点很重要:旧记忆中提到 PaperMod 曾因 LanguageCode、LanguageDirection 等弃用字段告警,现已修复,构建输出的干净程度可以作为"配置未回退"的证据。

8.2 本地服务

hugo server --bind 127.0.0.1 --port 1313 --baseURL http://localhost:1313/ --disableFastRender

逐个请求关键路径,全部返回 200:

路径用途
/首页(Profile 模式)
/blog/文章列表(自定义年份归档)
/fonts/LXGWBright-Regular.woff2本地字体,验证 static/ 映射正常

页面标题为 Ta0X1 の Blog,与 hugo.toml 一致。

8.3 推送验证

先手工执行 git push 确认认证与网络,再以部署脚本端到端复跑一次,确认"构建 → 提交 → 推送"三步闭环。两次均成功。

九、路径失效与脚本修正

系统重装往往伴随目录迁移,本次仓库从桌面移动到 C:\SpaceFloder\HugoBlog\CodingBlog\my-blog,而旧脚本把路径写死为桌面路径,属于典型的"换机即坏"。

第一轮修正(针对旧脚本):

  1. deploy.ps1:$blogDir = $PSScriptRoot,并增加 hugo 存在性检查,缺失时给出明确提示而非晦涩报错;
  2. new-post.ps1:改为 $PSScriptRoot\content\blog;同名文件已存在时递增 -01、-02;typora 不在 PATH 时回落到已知安装路径(本机为 C:\DATA\SoftWares\Typora\Typora\Typora.exe),再不行交给系统默认程序;
  3. News.bat:改用 %~dp0 定位。

第二轮(用户删除全部脚本后重建)见第十一节。旧脚本的这轮修正作为过程记录保留在此,说明"路径必须由脚本位置推导"这一原则的来由。

十、两次编码事故

这两次事故都与"编码 + 换行"有关,症状都不像编码问题,因此单独成节。

10.1 PowerShell 脚本必须为 UTF-8 with BOM

现象:powershell -File deploy.ps1 报 The string is missing the terminator,并指向文件第 34 行的一个 Write-Host。

根因:文件为 UTF-8 无 BOM。Windows PowerShell 5.1 在无 BOM 时按系统 ANSI(简体中文环境为 GBK)解码脚本;中文字符的多字节序列恰好吞掉了紧随其后的引号字节,导致语法解析错位。这类错误的特点是"报错位置与真实原因无关"。

处置:.ps1 一律保存为 UTF-8 with BOM,并用 PowerShell 自身的解析器预检:

[System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$null, [ref]$err)

BOM 化之后,PS 5.1 与 PS 7 的解析错误数均为 0。

10.2 批处理文件必须为 CRLF

现象:双击 Deploy.bat 报 'utionPolicy' is not recognized as an internal or external command,同时 if 块内的 echo 被当作命令执行。

根因:批处理文件以 LF 换行保存。cmd 解析批处理时按字节偏移读取行,LF 行尾会导致命令行被截断错位,于是 -ExecutionPolicy 变成 utionPolicy。这与编码无关,纯粹是换行符问题。

处置:.bat 统一为 UTF-8 无 BOM + CRLF,首行 @echo off,第二行 chcp 65001 >nul。三者的组合关系必须固定,缺一不可。

10.3 正文 Markdown 的编码

由脚本生成的 .md 一律为无 BOM 的 UTF-8。原因是带 BOM 时,Hugo 对 YAML front matter 的解析可能出现异常(首字段被 BOM 污染)。

十一、脚本重建

用户在环境恢复后删除了全部脚本,要求重建为"双击即用"。最终结构如下:

my-blog\
├── NewPost.bat        双击入口:新建文章
├── Deploy.bat         双击入口:一键部署
└── scripts\
    ├── new-post.ps1   实现:生成文章
    └── deploy.ps1     实现:构建与推送

设计上有六条明确取舍:

  1. 入口与实现分离。.bat 只负责 chcp、切换目录、转发参数(%*)、pause;所有逻辑在 .ps1 中。批处理的解析规则过于宽松,不适合承载复杂逻辑。
  2. 路径自推导。.ps1 用 $PSScriptRoot 的父目录作为仓库根,.bat 用 %~dp0,彻底消除硬编码。
  3. 减少交互。NewPost.bat 只询问标题;标签、分类、摘要通过参数传入(-Tags、-Categories、-Summary),避免每次回车三连。
  4. 失败即中止。构建失败立即退出,不执行 git add,杜绝把半成品提交上去。
  5. 空提交跳过。git add -A 后若索引无变化,跳过 git commit,只做推送。
  6. 前置风险提示。推送前检测 github.com 的解析结果,命中 198.18.0.0/16 时提示关闭 TUN 模式。

生成的 front matter 字段如下(部分字段与 hugo.toml 的全局默认重合,此处显式写出以便单篇覆盖):

字段取值说明
title用户输入双引号包裹并转义
date生成时刻(RFC3339)与文件名同源
draftfalse生成即发布,无需手动改草稿
authorTa0X1
tags / categories默认空数组可传参填充
ShowToc / TocOpentrue目录默认展开
ShowReadingTime / ShowWordCounttrue
ShowBreadCrumbs / ShowPostNavLinkstrue
commentstrue启用 Twikoo
searchHiddenfalse参与站内搜索
cover注释块需要封面时取消注释

十二、命名规则改为 14 位时间戳

原规则为 YYYYMMDD.md,同日多篇再加 -01、-02。为统一命名,改为本机时间的 14 位时间戳:

content/blog/20261012112345.md  ->  /p/20261012112345/

规则要点:

  • 秒级唯一,正常写作不会撞名;同一秒内重复生成才追加 -01;
  • 由于永久链接为 /p/:contentbasename/,文件名即链接,重命名等于改链接;
  • date 字段与文件名来自同一次 Get-Date,不会出现两者不一致。

现存 51 篇文章维持旧命名(33 个 YYYYMMDD、13 个 YYYYMMDD-NN、5 个 YYYYMMDDHHMM),因此站内目前是新旧并存状态。若日后要统一,必须同时为每篇写入 aliases,否则旧链接会 404。

十三、问题与根因一览

现象根因处置
所有 HTTPS 报 SEC_E_NO_CREDENTIALS受限执行环境拦截 TLS 凭据获取在放宽权限的 shell 中下载
Connection closed by 198.18.0.26Clash TUN 模式 fake-ip,SSH 不走系统代理关闭 TUN 模式;脚本增加前置提示
The string is missing the terminator.ps1 无 BOM + 中文,PS 5.1 按 GBK 解码存为 UTF-8 with BOM
'utionPolicy' is not recognized.bat 为 LF 换行改为 CRLF
git submodule 指向不存在路径.gitmodules 为失效声明,索引中无 gitlink删除 .gitmodules 与对应配置段
未启动代理时 Git 无法连接残留 http.https://github.com.proxy删除该配置,改用 SSH
受限环境中 ssh.exe 报 couldn't create signal pipe环境禁用命名管道,Git 的子进程无法创建管道推送在放宽权限下执行;用户本机终端不受影响

十四、当前环境清单

组件版本 / 位置
Git2.56.0.windows.3,C:\Program Files\Git
Hugov0.162.1 extended,C:\DATA\Tools\hugo\hugo.exe
SSH 客户端Windows OpenSSH 9.5p2
SSH 密钥ed25519,C:\Users\sinho\.ssh\id_ed25519
远程[email protected]:Sinhoole/sinhoole.github.io.git
分支main
站点https://blog.taoxi.ink
部署Vercel,HUGO_VERSION = 0.162.1

十五、日常操作

cd C:\SpaceFloder\HugoBlog\CodingBlog\my-blog
hugo server --bind 127.0.0.1 --port 1313 --baseURL http://localhost:1313/ --disableFastRender

写作与发布则直接双击:

  1. NewPost.bat:输入标题,回车;生成 content/blog/YYYYMMDDHHMMSS.md 并用 Typora 打开;
  2. 写完保存(无需改 draft);
  3. Deploy.bat:构建通过后自动提交并推送,Vercel 随即重新构建。