一、状态
重装系统意味着系统盘上的工具链全部消失,但只要博客源码目录放在非系统盘,内容与版本历史就仍然完整。接手时先做资产盘点,再决定动作。
| 项目 | 状态 |
|---|---|
| 仓库路径 | C:\SpaceFloder\HugoBlog\CodingBlog\my-blog |
| 原路径(历史记录中的) | C:\Users\sinho\Desktop\CodingBlog\my-blog |
| 远程仓库 | github.com/Sinhoole/sinhoole.github.io |
| 分支 | main,与 origin/main 同点 |
| 仓库 HEAD | 5964d8b |
.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.exe | 63.7 MB |
hugo_extended_0.162.1_windows-amd64.zip | 21.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.name | sinhoole | 与历史提交者一致,避免提交身份混杂 |
user.email | [email protected] | 同上 |
init.defaultBranch | main | 与远程默认分支一致 |
core.autocrlf | false | 仓库文件均为 LF,关闭自动转换以避免整文件 diff |
core.quotepath | false | 中文路径在 git status 中正常显示 |
pull.rebase | false | 默认合并策略,减少误操作 |
push.default | simple | 仅推送当前分支到同名远程分支 |
credential.helper | manager | 保留 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 中添加。验证命令:
ssh -T [email protected]
成功返回:
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,而旧脚本把路径写死为桌面路径,属于典型的"换机即坏"。
第一轮修正(针对旧脚本):
deploy.ps1:$blogDir = $PSScriptRoot,并增加hugo存在性检查,缺失时给出明确提示而非晦涩报错;new-post.ps1:改为$PSScriptRoot\content\blog;同名文件已存在时递增-01、-02;typora不在 PATH 时回落到已知安装路径(本机为C:\DATA\SoftWares\Typora\Typora\Typora.exe),再不行交给系统默认程序;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 实现:构建与推送
设计上有六条明确取舍:
- 入口与实现分离。
.bat只负责chcp、切换目录、转发参数(%*)、pause;所有逻辑在.ps1中。批处理的解析规则过于宽松,不适合承载复杂逻辑。 - 路径自推导。
.ps1用$PSScriptRoot的父目录作为仓库根,.bat用%~dp0,彻底消除硬编码。 - 减少交互。
NewPost.bat只询问标题;标签、分类、摘要通过参数传入(-Tags、-Categories、-Summary),避免每次回车三连。 - 失败即中止。构建失败立即退出,不执行
git add,杜绝把半成品提交上去。 - 空提交跳过。
git add -A后若索引无变化,跳过git commit,只做推送。 - 前置风险提示。推送前检测
github.com的解析结果,命中198.18.0.0/16时提示关闭 TUN 模式。
生成的 front matter 字段如下(部分字段与 hugo.toml 的全局默认重合,此处显式写出以便单篇覆盖):
| 字段 | 取值 | 说明 |
|---|---|---|
title | 用户输入 | 双引号包裹并转义 |
date | 生成时刻(RFC3339) | 与文件名同源 |
draft | false | 生成即发布,无需手动改草稿 |
author | Ta0X1 | |
tags / categories | 默认空数组 | 可传参填充 |
ShowToc / TocOpen | true | 目录默认展开 |
ShowReadingTime / ShowWordCount | true | |
ShowBreadCrumbs / ShowPostNavLinks | true | |
comments | true | 启用 Twikoo |
searchHidden | false | 参与站内搜索 |
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.26 | Clash 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 的子进程无法创建管道 | 推送在放宽权限下执行;用户本机终端不受影响 |
十四、当前环境清单
| 组件 | 版本 / 位置 |
|---|---|
| Git | 2.56.0.windows.3,C:\Program Files\Git |
| Hugo | v0.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
写作与发布则直接双击:
NewPost.bat:输入标题,回车;生成content/blog/YYYYMMDDHHMMSS.md并用 Typora 打开;- 写完保存(无需改
draft); Deploy.bat:构建通过后自动提交并推送,Vercel 随即重新构建。