<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Hugo on Ta0X1 の Blog</title><link>https://blog.taoxi.ink/tags/hugo/</link><description>Recent content in Hugo on Ta0X1 の Blog</description><generator>Hugo</generator><language>zh-CN</language><copyright>2025-2026 Ta0X1 の Blog</copyright><lastBuildDate>Sun, 25 Oct 2026 17:12:37 +0800</lastBuildDate><atom:link href="https://blog.taoxi.ink/tags/hugo/index.xml" rel="self" type="application/rss+xml"/><item><title>重装系统后怎么迁移博客？</title><link>https://blog.taoxi.ink/p/20261025171237/</link><pubDate>Sun, 25 Oct 2026 17:12:37 +0800</pubDate><guid>https://blog.taoxi.ink/p/20261025171237/</guid><description>&lt;h2 id="一状态"&gt;一、状态&lt;/h2&gt;
&lt;p&gt;重装系统意味着系统盘上的工具链全部消失，但只要博客源码目录放在非系统盘，内容与版本历史就仍然完整。接手时先做资产盘点，再决定动作。&lt;/p&gt;
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;项目&lt;/th&gt;
&lt;th&gt;状态&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;仓库路径&lt;/td&gt;
&lt;td&gt;&lt;code&gt;C:\SpaceFloder\HugoBlog\CodingBlog\my-blog&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;原路径（历史记录中的）&lt;/td&gt;
&lt;td&gt;&lt;code&gt;C:\Users\sinho\Desktop\CodingBlog\my-blog&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;远程仓库&lt;/td&gt;
&lt;td&gt;&lt;code&gt;github.com/Sinhoole/sinhoole.github.io&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;分支&lt;/td&gt;
&lt;td&gt;&lt;code&gt;main&lt;/code&gt;，与 &lt;code&gt;origin/main&lt;/code&gt; 同点&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;仓库 HEAD&lt;/td&gt;
&lt;td&gt;&lt;code&gt;5964d8b&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;.git&lt;/code&gt; 对象库&lt;/td&gt;
&lt;td&gt;完整（含 pack、index、refs）&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Git&lt;/td&gt;
&lt;td&gt;未安装&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hugo&lt;/td&gt;
&lt;td&gt;未安装&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Node / pnpm&lt;/td&gt;
&lt;td&gt;未安装&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;
&lt;p&gt;结论先行：数据无损，缺的只是&amp;quot;能跑起来&amp;quot;的工具。因此本次工作的重点是恢复工具链、恢复认证、修正因目录迁移而失效的路径，并重新建立可一键执行的脚本。&lt;/p&gt;</description><content:encoded><![CDATA[<h2 id="一状态">一、状态</h2>
<p>重装系统意味着系统盘上的工具链全部消失，但只要博客源码目录放在非系统盘，内容与版本历史就仍然完整。接手时先做资产盘点，再决定动作。</p>
<table>
	<thead>
			<tr>
					<th>项目</th>
					<th>状态</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>仓库路径</td>
					<td><code>C:\SpaceFloder\HugoBlog\CodingBlog\my-blog</code></td>
			</tr>
			<tr>
					<td>原路径（历史记录中的）</td>
					<td><code>C:\Users\sinho\Desktop\CodingBlog\my-blog</code></td>
			</tr>
			<tr>
					<td>远程仓库</td>
					<td><code>github.com/Sinhoole/sinhoole.github.io</code></td>
			</tr>
			<tr>
					<td>分支</td>
					<td><code>main</code>，与 <code>origin/main</code> 同点</td>
			</tr>
			<tr>
					<td>仓库 HEAD</td>
					<td><code>5964d8b</code></td>
			</tr>
			<tr>
					<td><code>.git</code> 对象库</td>
					<td>完整（含 pack、index、refs）</td>
			</tr>
			<tr>
					<td>Git</td>
					<td>未安装</td>
			</tr>
			<tr>
					<td>Hugo</td>
					<td>未安装</td>
			</tr>
			<tr>
					<td>Node / pnpm</td>
					<td>未安装</td>
			</tr>
	</tbody>
</table>
<p>结论先行：数据无损，缺的只是&quot;能跑起来&quot;的工具。因此本次工作的重点是恢复工具链、恢复认证、修正因目录迁移而失效的路径，并重新建立可一键执行的脚本。</p>
<h2 id="二环境勘查">二、环境勘查</h2>
<p>先确认&quot;缺什么&quot;，再决定&quot;装什么&quot;。检查分三类。</p>
<h3 id="21-命令可用性">2.1 命令可用性</h3>
<p>逐个探测 <code>hugo</code>、<code>git</code>、<code>node</code>、<code>npm</code>、<code>pnpm</code>、<code>winget</code>、<code>scoop</code>、<code>choco</code>、<code>go</code>、<code>python</code>。</p>
<p>结果：<code>hugo</code>、<code>git</code>、<code>node</code>、<code>npm</code>、<code>pnpm</code>、<code>scoop</code>、<code>choco</code>、<code>go</code> 均不存在；<code>python</code> 是 Microsoft Store 的占位程序；<code>winget</code> 存在但不可用，执行 <code>winget --version</code> 返回 <code>0x8A150001</code>，无法承担安装任务。</p>
<h3 id="22-全盘检索既有二进制">2.2 全盘检索既有二进制</h3>
<p>在 <code>C:\DATA</code>、<code>C:\SpaceFloder</code>、<code>C:\Program Files</code>、<code>%LOCALAPPDATA%</code> 四个常见根目录做四级深度检索，查找 <code>git.exe</code> 与 <code>hugo.exe</code>，结果为空。排除了&quot;已安装但未加入 PATH&quot;的可能，确认必须重新安装。</p>
<h3 id="23-仓库内部状态">2.3 仓库内部状态</h3>
<p>读取 <code>.git/config</code>、<code>.git/HEAD</code>、<code>.git/refs</code>、<code>.git/objects</code>，确认分支与历史完整；同时确认旧配置里保留了两条重要信息：一是本地提交身份（<code>sinhoole</code> / <code>sinhoole@outlook.com</code>），二是为 <code>https://github.com</code> 设置的 SOCKS5 代理 <code>socks5://127.0.0.1:7897</code>。</p>
<p>此外通读了仓库内的 <code>.workbuddy/memory/</code> 六份记忆与 <code>project-summary.md</code>，用以复原此前的技术约定，避免&quot;重新发明&quot;配置：</p>
<ul>
<li>主题为 PaperMod，永久链接为 <code>blog = '/p/:contentbasename/'</code>；</li>
<li>评论系统为 Twikoo（<code>envId = https://twikoo.taoxi.ink</code>）；</li>
<li>字体为本地 <code>LXGWBright</code>（<code>static/fonts/LXGWBright-Regular.woff2</code>），由 <code>assets/css/extended/custom.css</code> 以 <code>@font-face</code> 加载；</li>
<li>数学公式通过 Goldmark passthrough 与 KaTeX 渲染；</li>
<li>文章命名早期为纯数字（<code>YYYYMMDD</code>、<code>YYYYMMDD-NN</code>）。</li>
</ul>
<h2 id="三网络诊断">三、网络诊断</h2>
<p>本次共出现两次网络相关的误判，均为&quot;现象相似、根因不同&quot;，值得单独记录。</p>
<h3 id="31-第一次误判把执行环境的限制当成线路封锁">3.1 第一次误判：把执行环境的限制当成线路封锁</h3>
<p>在受限 shell 中访问任意 HTTPS 站点（包括国内可达站点）均报同一错误：</p>
<pre tabindex="0"><code>curl: (35) schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS (0x8009030e)
</code></pre><p>若真是线路封锁，不可能对全部域名返回完全相同的错误，且错误发生在 TLS 握手开始之前的凭据获取阶段。据此判断：问题在 TLS 栈的凭据获取，属于执行环境限制，而非网络。</p>
<p>验证方式有两条：其一，改用宿主侧请求工具访问 <code>https://github.com</code>，得到 HTTP 200；其二，在放宽限制的 shell 中直连下载安装包，速度正常。由此确认 GitHub 可直连，下载不需要代理。</p>
<h3 id="32-第二次误判系统代理指向未启动的客户端">3.2 第二次误判：系统代理指向未启动的客户端</h3>
<p>注册表 <code>HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings</code> 中 <code>ProxyEnable = 1</code>、<code>ProxyServer = 127.0.0.1:7897</code>，但 7897 端口无监听进程。这说明代理软件（Clash Verge）已退出，而系统代理开关仍停留在开启状态。</p>
<p>影响：所有遵循系统代理的程序（浏览器、<code>Invoke-WebRequest</code> 等）会连接一个不存在的端口而失败。处置：以 <code>--noproxy '*'</code> 绕过系统代理完成下载；同时删除 Git 中遗留的 <code>http.https://github.com.proxy</code>，避免&quot;未启动代理就推不上去&quot;的隐性依赖。</p>
<h3 id="33-第三次现象tun-模式导致-ssh-无法建立">3.3 第三次现象：TUN 模式导致 SSH 无法建立</h3>
<p>后续在推送阶段出现：</p>
<pre tabindex="0"><code>ssh: Connection closed by 198.18.0.26 port 443
</code></pre><p><code>198.18.0.0/16</code> 是 Clash 的 fake-ip 段。开启&quot;虚拟网卡（TUN）&ldquo;模式后，DNS 会把所有域名解析到该段，由代理内核接管流量；而 SSH 客户端不遵循系统代理，连接被直接关闭。关闭 TUN 后，<code>github.com</code> 立即恢复解析为真实地址（<code>20.205.243.166</code>），推送恢复正常。</p>
<p>这一条已固化进部署脚本：推送前若发现解析结果落在 <code>198.18.0.0/16</code>，脚本会主动提示关闭 TUN 模式。</p>
<h2 id="四安装-git-与-hugo">四、安装 Git 与 Hugo</h2>
<h3 id="41-版本选择">4.1 版本选择</h3>
<p>Hugo 固定为 <code>v0.162.1 extended</code>，理由不是&quot;稳定&rdquo;，而是<strong>与线上一致</strong>：<code>vercel.json</code> 中写死了 <code>HUGO_VERSION = 0.162.1</code>，本地若用别的版本，构建产物可能与线上不同，排查问题时会产生噪音。当时最新版已是 <code>v0.168.0</code>，本次刻意不升级。</p>
<p>Git 取当时的稳定版 <code>2.56.0.3</code>（Git for Windows）。</p>
<h3 id="42-下载">4.2 下载</h3>
<p>在放宽限制的 shell 中执行 <code>curl -L</code> 直连下载，不经过代理：</p>
<table>
	<thead>
			<tr>
					<th>文件</th>
					<th>大小</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>Git-2.56.0.3-64-bit.exe</code></td>
					<td>63.7 MB</td>
			</tr>
			<tr>
					<td><code>hugo_extended_0.162.1_windows-amd64.zip</code></td>
					<td>21.4 MB</td>
			</tr>
	</tbody>
</table>
<h3 id="43-安装">4.3 安装</h3>
<p>Git 使用 Inno Setup 的静默参数，以 <code>-Verb RunAs</code> 触发 UAC，由用户在弹窗确认：</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>Start-Process -FilePath $gitExe -Verb RunAs -Wait `
</span></span><span style="display:flex;"><span>  -ArgumentList <span style="color:#e6db74">&#39;/VERYSILENT&#39;</span>,<span style="color:#e6db74">&#39;/NORESTART&#39;</span>,<span style="color:#e6db74">&#39;/SP-&#39;</span>,<span style="color:#e6db74">&#39;/NOCANCEL&#39;</span>
</span></span></code></pre></div><p>安装目录为 <code>C:\Program Files\Git</code>，安装器同时写入机器级 PATH。</p>
<p>Hugo 官方只提供压缩包，没有安装程序。解压至 <code>C:\DATA\Tools\hugo</code>，得到单一可执行文件 <code>hugo.exe</code>（约 62 MB）。</p>
<p>随后把两个目录追加到用户级 PATH：</p>
<pre tabindex="0"><code>C:\Program Files\Git\cmd
C:\DATA\Tools\hugo
</code></pre><p>验证结果：</p>
<pre tabindex="0"><code>git version 2.56.0.windows.3
hugo v0.162.1-bba860e3eda3091efe8c6d1a96bc49a29ad2d5f6+extended windows/amd64
</code></pre><h3 id="44-关于-node">4.4 关于 Node</h3>
<p>本站构建不需要 Node。PaperMod 没有 <code>package.json</code>，样式与脚本由 Hugo extended 内置的管道处理（主题的 <code>head.html</code> 使用 <code>resources.Get | js.Build</code>，即内置 esbuild）。因此未安装 Node 与 pnpm，避免引入无用依赖。</p>
<h2 id="五git-身份与远程">五、Git 身份与远程</h2>
<p>重装后全局配置丢失，仅仓库内的本地配置仍在。补齐全局配置如下：</p>
<table>
	<thead>
			<tr>
					<th>配置项</th>
					<th>取值</th>
					<th>理由</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>user.name</code></td>
					<td><code>sinhoole</code></td>
					<td>与历史提交者一致，避免提交身份混杂</td>
			</tr>
			<tr>
					<td><code>user.email</code></td>
					<td><code>sinhoole@outlook.com</code></td>
					<td>同上</td>
			</tr>
			<tr>
					<td><code>init.defaultBranch</code></td>
					<td><code>main</code></td>
					<td>与远程默认分支一致</td>
			</tr>
			<tr>
					<td><code>core.autocrlf</code></td>
					<td><code>false</code></td>
					<td>仓库文件均为 LF，关闭自动转换以避免整文件 diff</td>
			</tr>
			<tr>
					<td><code>core.quotepath</code></td>
					<td><code>false</code></td>
					<td>中文路径在 <code>git status</code> 中正常显示</td>
			</tr>
			<tr>
					<td><code>pull.rebase</code></td>
					<td><code>false</code></td>
					<td>默认合并策略，减少误操作</td>
			</tr>
			<tr>
					<td><code>push.default</code></td>
					<td><code>simple</code></td>
					<td>仅推送当前分支到同名远程分支</td>
			</tr>
			<tr>
					<td><code>credential.helper</code></td>
					<td><code>manager</code></td>
					<td>保留 HTTPS 通道的凭据能力，作为兜底</td>
			</tr>
	</tbody>
</table>
<p>远程地址由 HTTPS 切换为 SSH：</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>git remote set-url origin git@github.com<span style="color:#960050;background-color:#1e0010">:</span>Sinhoole/sinhoole.github.io.git
</span></span></code></pre></div><h2 id="六ssh-密钥与认证">六、SSH 密钥与认证</h2>
<h3 id="61-生成密钥">6.1 生成密钥</h3>
<p>使用系统自带 OpenSSH（<code>C:\Windows\System32\OpenSSH\ssh-keygen.exe</code>）生成 ed25519 密钥对：</p>
<pre tabindex="0"><code>私钥  C:\Users\sinho\.ssh\id_ed25519
公钥  C:\Users\sinho\.ssh\id_ed25519.pub
指纹  SHA256:RXec6iNOpSiHPFsq6P6XDR79x+4WFx4ygEuron5hMZU
</code></pre><p>未设置口令，目的是让双击脚本可以无交互完成推送；代价是私钥以明文形式存在于用户目录，安全性依赖系统账户本身。若后续有更高要求，应改为带口令并配合 <code>ssh-agent</code>。</p>
<h3 id="62-客户端配置">6.2 客户端配置</h3>
<p>在 <code>~/.ssh/config</code> 中固定走 443 端口：</p>
<pre tabindex="0"><code>Host github.com
    HostName ssh.github.com
    Port 443
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
</code></pre><p><code>ssh.github.com:443</code> 与 <code>github.com:22</code> 提供相同服务，但在受限网络中更容易连通，因此作为默认配置写入。</p>
<h3 id="63-授权与验证">6.3 授权与验证</h3>
<p>公钥由用户在 GitHub 的 Settings → SSH and GPG keys 中添加。验证命令：</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>ssh -T git@github.com
</span></span></code></pre></div><p>成功返回：</p>
<pre tabindex="0"><code>Hi Sinhoole! You&#39;ve successfully authenticated, but GitHub does not provide shell access.
</code></pre><p>补充说明：添加公钥之前首次测试返回 <code>Permission denied (publickey)</code>。这个错误恰好说明<strong>传输层已连通、仅缺授权</strong>，因此可以断定问题不在网络，而在密钥注册。区分&quot;连不上&quot;与&quot;没授权&quot;是排查此类问题的关键一步。</p>
<h2 id="七清理失效配置">七、清理失效配置</h2>
<h3 id="71-gitmodules-是无效声明">7.1 <code>.gitmodules</code> 是无效声明</h3>
<p>仓库根目录存在 <code>.gitmodules</code>，声明子模块 <code>hugo-PaperMod</code>，路径为 <code>hugo-PaperMod</code>。但事实是：</p>
<ul>
<li><code>git ls-files -s</code> 中不存在任何 <code>mode 160000</code> 条目；</li>
<li><code>themes/PaperMod</code> 下的 126 个文件全部以普通文件（<code>mode 100644</code>）入库。</li>
</ul>
<p>也就是说，主题是以&quot;vendored&quot;方式并入主仓库的，子模块从未真正启用。保留 <code>.gitmodules</code> 会让 <code>git submodule</code> 系列命令指向一个不存在的路径，属于会误导后续维护的残留。处置：删除 <code>.gitmodules</code>，并移除 <code>.git/config</code> 中对应的 <code>submodule.*</code> 段。</p>
<p>需要指出的是，<code>themes/PaperMod/.git</code> 仍指向 <code>.git/modules/hugo-PaperMod</code>，这是历史遗留；由于索引中没有 gitlink，它不影响构建，也不影响提交。本次未做删除，避免无谓风险。</p>
<h3 id="72-删除隐性的代理依赖">7.2 删除隐性的代理依赖</h3>
<p>删除 <code>.git/config</code> 中的 <code>http.https://github.com.proxy = socks5://127.0.0.1:7897</code>。理由见 3.2：该配置会让 Git 在代理未启动时直接失败，而实测直连可用，属于负资产。</p>
<h2 id="八构建与本地验证">八、构建与本地验证</h2>
<p>工具装好之后，先验证&quot;能构建&quot;，再验证&quot;能推送&quot;，顺序不可颠倒。</p>
<h3 id="81-生产构建">8.1 生产构建</h3>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>hugo --gc --minify
</span></span></code></pre></div><p>结果：378 个页面、198 个别名页，输出约 580 个文件、约 10 MB，<strong>无任何警告</strong>。这一点很重要：旧记忆中提到 PaperMod 曾因 <code>LanguageCode</code>、<code>LanguageDirection</code> 等弃用字段告警，现已修复，构建输出的干净程度可以作为&quot;配置未回退&quot;的证据。</p>
<h3 id="82-本地服务">8.2 本地服务</h3>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>hugo server --bind <span style="color:#ae81ff">127.0</span>.0.1 --port <span style="color:#ae81ff">1313</span> --baseURL http<span style="color:#960050;background-color:#1e0010">:</span>//localhost<span style="color:#960050;background-color:#1e0010">:</span><span style="color:#ae81ff">1313</span>/ --disableFastRender
</span></span></code></pre></div><p>逐个请求关键路径，全部返回 200：</p>
<table>
	<thead>
			<tr>
					<th>路径</th>
					<th>用途</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>/</code></td>
					<td>首页（Profile 模式）</td>
			</tr>
			<tr>
					<td><code>/blog/</code></td>
					<td>文章列表（自定义年份归档）</td>
			</tr>
			<tr>
					<td><code>/fonts/LXGWBright-Regular.woff2</code></td>
					<td>本地字体，验证 <code>static/</code> 映射正常</td>
			</tr>
	</tbody>
</table>
<p>页面标题为 <code>Ta0X1 の Blog</code>，与 <code>hugo.toml</code> 一致。</p>
<h3 id="83-推送验证">8.3 推送验证</h3>
<p>先手工执行 <code>git push</code> 确认认证与网络，再以部署脚本端到端复跑一次，确认&quot;构建 → 提交 → 推送&quot;三步闭环。两次均成功。</p>
<h2 id="九路径失效与脚本修正">九、路径失效与脚本修正</h2>
<p>系统重装往往伴随目录迁移，本次仓库从桌面移动到 <code>C:\SpaceFloder\HugoBlog\CodingBlog\my-blog</code>，而旧脚本把路径写死为桌面路径，属于典型的&quot;换机即坏&quot;。</p>
<p>第一轮修正（针对旧脚本）：</p>
<ol>
<li><code>deploy.ps1</code>：<code>$blogDir = $PSScriptRoot</code>，并增加 <code>hugo</code> 存在性检查，缺失时给出明确提示而非晦涩报错；</li>
<li><code>new-post.ps1</code>：改为 <code>$PSScriptRoot\content\blog</code>；同名文件已存在时递增 <code>-01</code>、<code>-02</code>；<code>typora</code> 不在 PATH 时回落到已知安装路径（本机为 <code>C:\DATA\SoftWares\Typora\Typora\Typora.exe</code>），再不行交给系统默认程序；</li>
<li><code>News.bat</code>：改用 <code>%~dp0</code> 定位。</li>
</ol>
<p>第二轮（用户删除全部脚本后重建）见第十一节。旧脚本的这轮修正作为过程记录保留在此，说明&quot;路径必须由脚本位置推导&quot;这一原则的来由。</p>
<h2 id="十两次编码事故">十、两次编码事故</h2>
<p>这两次事故都与&quot;编码 + 换行&quot;有关，症状都不像编码问题，因此单独成节。</p>
<h3 id="101-powershell-脚本必须为-utf-8-with-bom">10.1 PowerShell 脚本必须为 UTF-8 with BOM</h3>
<p>现象：<code>powershell -File deploy.ps1</code> 报 <code>The string is missing the terminator</code>，并指向文件第 34 行的一个 <code>Write-Host</code>。</p>
<p>根因：文件为 UTF-8 无 BOM。Windows PowerShell 5.1 在无 BOM 时按系统 ANSI（简体中文环境为 GBK）解码脚本；中文字符的多字节序列恰好吞掉了紧随其后的引号字节，导致语法解析错位。这类错误的特点是&quot;报错位置与真实原因无关&quot;。</p>
<p>处置：<code>.ps1</code> 一律保存为 UTF-8 with BOM，并用 PowerShell 自身的解析器预检：</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>[<span style="color:#66d9ef">System.Management.Automation.Language.Parser</span>]::ParseFile($path, [<span style="color:#66d9ef">ref</span>]$null, [<span style="color:#66d9ef">ref</span>]$err)
</span></span></code></pre></div><p>BOM 化之后，PS 5.1 与 PS 7 的解析错误数均为 0。</p>
<h3 id="102-批处理文件必须为-crlf">10.2 批处理文件必须为 CRLF</h3>
<p>现象：双击 <code>Deploy.bat</code> 报 <code>'utionPolicy' is not recognized as an internal or external command</code>，同时 <code>if</code> 块内的 <code>echo</code> 被当作命令执行。</p>
<p>根因：批处理文件以 LF 换行保存。cmd 解析批处理时按字节偏移读取行，LF 行尾会导致命令行被截断错位，于是 <code>-ExecutionPolicy</code> 变成 <code>utionPolicy</code>。这与编码无关，纯粹是换行符问题。</p>
<p>处置：<code>.bat</code> 统一为 UTF-8 无 BOM + CRLF，首行 <code>@echo off</code>，第二行 <code>chcp 65001 &gt;nul</code>。三者的组合关系必须固定，缺一不可。</p>
<h3 id="103-正文-markdown-的编码">10.3 正文 Markdown 的编码</h3>
<p>由脚本生成的 <code>.md</code> 一律为无 BOM 的 UTF-8。原因是带 BOM 时，Hugo 对 YAML front matter 的解析可能出现异常（首字段被 BOM 污染）。</p>
<h2 id="十一脚本重建">十一、脚本重建</h2>
<p>用户在环境恢复后删除了全部脚本，要求重建为&quot;双击即用&quot;。最终结构如下：</p>
<pre tabindex="0"><code>my-blog\
├── NewPost.bat        双击入口：新建文章
├── Deploy.bat         双击入口：一键部署
└── scripts\
    ├── new-post.ps1   实现：生成文章
    └── deploy.ps1     实现：构建与推送
</code></pre><p>设计上有六条明确取舍：</p>
<ol>
<li><strong>入口与实现分离</strong>。<code>.bat</code> 只负责 <code>chcp</code>、切换目录、转发参数（<code>%*</code>）、<code>pause</code>；所有逻辑在 <code>.ps1</code> 中。批处理的解析规则过于宽松，不适合承载复杂逻辑。</li>
<li><strong>路径自推导</strong>。<code>.ps1</code> 用 <code>$PSScriptRoot</code> 的父目录作为仓库根，<code>.bat</code> 用 <code>%~dp0</code>，彻底消除硬编码。</li>
<li><strong>减少交互</strong>。<code>NewPost.bat</code> 只询问标题；标签、分类、摘要通过参数传入（<code>-Tags</code>、<code>-Categories</code>、<code>-Summary</code>），避免每次回车三连。</li>
<li><strong>失败即中止</strong>。构建失败立即退出，不执行 <code>git add</code>，杜绝把半成品提交上去。</li>
<li><strong>空提交跳过</strong>。<code>git add -A</code> 后若索引无变化，跳过 <code>git commit</code>，只做推送。</li>
<li><strong>前置风险提示</strong>。推送前检测 <code>github.com</code> 的解析结果，命中 <code>198.18.0.0/16</code> 时提示关闭 TUN 模式。</li>
</ol>
<p>生成的 front matter 字段如下（部分字段与 <code>hugo.toml</code> 的全局默认重合，此处显式写出以便单篇覆盖）：</p>
<table>
	<thead>
			<tr>
					<th>字段</th>
					<th>取值</th>
					<th>说明</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>title</code></td>
					<td>用户输入</td>
					<td>双引号包裹并转义</td>
			</tr>
			<tr>
					<td><code>date</code></td>
					<td>生成时刻（RFC3339）</td>
					<td>与文件名同源</td>
			</tr>
			<tr>
					<td><code>draft</code></td>
					<td><code>false</code></td>
					<td>生成即发布，无需手动改草稿</td>
			</tr>
			<tr>
					<td><code>author</code></td>
					<td><code>Ta0X1</code></td>
					<td></td>
			</tr>
			<tr>
					<td><code>tags</code> / <code>categories</code></td>
					<td>默认空数组</td>
					<td>可传参填充</td>
			</tr>
			<tr>
					<td><code>ShowToc</code> / <code>TocOpen</code></td>
					<td><code>true</code></td>
					<td>目录默认展开</td>
			</tr>
			<tr>
					<td><code>ShowReadingTime</code> / <code>ShowWordCount</code></td>
					<td><code>true</code></td>
					<td></td>
			</tr>
			<tr>
					<td><code>ShowBreadCrumbs</code> / <code>ShowPostNavLinks</code></td>
					<td><code>true</code></td>
					<td></td>
			</tr>
			<tr>
					<td><code>comments</code></td>
					<td><code>true</code></td>
					<td>启用 Twikoo</td>
			</tr>
			<tr>
					<td><code>searchHidden</code></td>
					<td><code>false</code></td>
					<td>参与站内搜索</td>
			</tr>
			<tr>
					<td><code>cover</code></td>
					<td>注释块</td>
					<td>需要封面时取消注释</td>
			</tr>
	</tbody>
</table>
<h2 id="十二命名规则改为-14-位时间戳">十二、命名规则改为 14 位时间戳</h2>
<p>原规则为 <code>YYYYMMDD.md</code>，同日多篇再加 <code>-01</code>、<code>-02</code>。为统一命名，改为本机时间的 14 位时间戳：</p>
<pre tabindex="0"><code>content/blog/20261012112345.md  -&gt;  /p/20261012112345/
</code></pre><p>规则要点：</p>
<ul>
<li>秒级唯一，正常写作不会撞名；同一秒内重复生成才追加 <code>-01</code>；</li>
<li>由于永久链接为 <code>/p/:contentbasename/</code>，<strong>文件名即链接</strong>，重命名等于改链接；</li>
<li><code>date</code> 字段与文件名来自同一次 <code>Get-Date</code>，不会出现两者不一致。</li>
</ul>
<p>现存 51 篇文章维持旧命名（33 个 <code>YYYYMMDD</code>、13 个 <code>YYYYMMDD-NN</code>、5 个 <code>YYYYMMDDHHMM</code>），因此站内目前是新旧并存状态。若日后要统一，必须同时为每篇写入 <code>aliases</code>，否则旧链接会 404。</p>
<h2 id="十三问题与根因一览">十三、问题与根因一览</h2>
<table>
	<thead>
			<tr>
					<th>现象</th>
					<th>根因</th>
					<th>处置</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>所有 HTTPS 报 <code>SEC_E_NO_CREDENTIALS</code></td>
					<td>受限执行环境拦截 TLS 凭据获取</td>
					<td>在放宽权限的 shell 中下载</td>
			</tr>
			<tr>
					<td><code>Connection closed by 198.18.0.26</code></td>
					<td>Clash TUN 模式 fake-ip，SSH 不走系统代理</td>
					<td>关闭 TUN 模式；脚本增加前置提示</td>
			</tr>
			<tr>
					<td><code>The string is missing the terminator</code></td>
					<td><code>.ps1</code> 无 BOM + 中文，PS 5.1 按 GBK 解码</td>
					<td>存为 UTF-8 with BOM</td>
			</tr>
			<tr>
					<td><code>'utionPolicy' is not recognized</code></td>
					<td><code>.bat</code> 为 LF 换行</td>
					<td>改为 CRLF</td>
			</tr>
			<tr>
					<td><code>git submodule</code> 指向不存在路径</td>
					<td><code>.gitmodules</code> 为失效声明，索引中无 gitlink</td>
					<td>删除 <code>.gitmodules</code> 与对应配置段</td>
			</tr>
			<tr>
					<td>未启动代理时 Git 无法连接</td>
					<td>残留 <code>http.https://github.com.proxy</code></td>
					<td>删除该配置，改用 SSH</td>
			</tr>
			<tr>
					<td>受限环境中 <code>ssh.exe</code> 报 <code>couldn't create signal pipe</code></td>
					<td>环境禁用命名管道，Git 的子进程无法创建管道</td>
					<td>推送在放宽权限下执行；用户本机终端不受影响</td>
			</tr>
	</tbody>
</table>
<h2 id="十四当前环境清单">十四、当前环境清单</h2>
<table>
	<thead>
			<tr>
					<th>组件</th>
					<th>版本 / 位置</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Git</td>
					<td><code>2.56.0.windows.3</code>，<code>C:\Program Files\Git</code></td>
			</tr>
			<tr>
					<td>Hugo</td>
					<td><code>v0.162.1 extended</code>，<code>C:\DATA\Tools\hugo\hugo.exe</code></td>
			</tr>
			<tr>
					<td>SSH 客户端</td>
					<td>Windows OpenSSH 9.5p2</td>
			</tr>
			<tr>
					<td>SSH 密钥</td>
					<td><code>ed25519</code>，<code>C:\Users\sinho\.ssh\id_ed25519</code></td>
			</tr>
			<tr>
					<td>远程</td>
					<td><code>git@github.com:Sinhoole/sinhoole.github.io.git</code></td>
			</tr>
			<tr>
					<td>分支</td>
					<td><code>main</code></td>
			</tr>
			<tr>
					<td>站点</td>
					<td><code>https://blog.taoxi.ink</code></td>
			</tr>
			<tr>
					<td>部署</td>
					<td>Vercel，<code>HUGO_VERSION = 0.162.1</code></td>
			</tr>
	</tbody>
</table>
<h2 id="十五日常操作">十五、日常操作</h2>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-powershell" data-lang="powershell"><span style="display:flex;"><span>cd C:\SpaceFloder\HugoBlog\CodingBlog\my-blog
</span></span><span style="display:flex;"><span>hugo server --bind <span style="color:#ae81ff">127.0</span>.0.1 --port <span style="color:#ae81ff">1313</span> --baseURL http<span style="color:#960050;background-color:#1e0010">:</span>//localhost<span style="color:#960050;background-color:#1e0010">:</span><span style="color:#ae81ff">1313</span>/ --disableFastRender
</span></span></code></pre></div><p>写作与发布则直接双击：</p>
<ol>
<li><code>NewPost.bat</code>：输入标题，回车；生成 <code>content/blog/YYYYMMDDHHMMSS.md</code> 并用 Typora 打开；</li>
<li>写完保存（无需改 <code>draft</code>）；</li>
<li><code>Deploy.bat</code>：构建通过后自动提交并推送，Vercel 随即重新构建。</li>
</ol>
]]></content:encoded></item></channel></rss>