在明确了利用 Hugo 搭建纯静态博客的目标后，第一步是搭建本地工作流。
我的核心诉求是“无缝衔接”：我希望平时记笔记依然在 Obsidian 里进行，写完后能直接通过 Git 推送到云端，由服务器自动渲染成网页。为了实现这个目标，我把整个网站的源码文件夹作为了一个独立的 Obsidian Vault（知识库）打开。
理论上，这套工作流非常清晰。但实际上，当知识库（写作环境）和代码库（编译环境）强行塞进同一个物理文件夹时，系统很快就失控了。
1. 冲突的必然性：当文本编辑器遇上静态生成器
问题出在两个软件的底层运行机制上。
Obsidian 是一个重度依赖本地缓存的软件。为了维持插件、主题和双链索引，它会在根目录下不断更新一个庞大的 .obsidian/ 隐藏文件夹。
另一边，Hugo 在每次本地预览（hugo server）或编译时，都会在根目录生成 public/ 产物文件夹，并写入 .hugo_build.lock 等底层构建锁文件。
当我在根目录执行 git add . 时，Git 把这堆杂乱无章的私有配置文件和编译废料全部打包进了暂存区。这导致了两个严重后果：
第一，Git 追踪树变得无比庞大，每次 commit 都能带出几百个无关文件的变更；
第二，极其容易引发冲突，特别是 Obsidian 的工作区缓存（workspace.json）几乎每秒都在变。
这在工程上是典型的“职责不清”和“环境污染”。
2. 系统解耦：配置严格的防污边界
为了让系统恢复稳定，必须在物理层面划定清晰的边界。Git 的职责是版本控制，它只需要关注我的 Markdown 源码（content/ 目录）和网站的骨架配置（hugo.toml 等）。至于 .obsidian/ 里的私人配置和 public/ 里的编译产物，绝对不能进入版本控制流。
我在项目根目录重新配置了极其严格的 .gitignore 规则：
# 核心隔离：拦截 Obsidian 私有环境
.obsidian/
# 编译废料与构建锁隔离
public/
resources/
.hugo_build.lock
这套规则的逻辑很简单：斩断 Git 对本地写作环境和本地编译产物的感知，强行完成两个系统的解耦。
3. 暂存区清洗：修正历史状态
虽然规则定好了，但对于已经被污染的 Git 仓库来说，仅仅修改 .gitignore 是无效的。因为那些垃圾文件已经被 Git 的缓存（Cache）记录，Git 依然会追踪它们的后续变更。
为了不破坏硬盘上的物理文件（我还要留着 .obsidian 继续做笔记），我必须对 Git 的暂存区进行一次定向清洗。在终端里，我执行了这行指令：
git rm -r --cached .
--cached 参数是关键。它告诉 Git：“清空你的追踪记忆，但不要碰我本地的任何文件。” 执行完毕后，整个仓库的追踪状态被重置。紧接着，我重新将干净的文件拉入暂存区并提交，彻底清除了污染源。
此外，在处理早期测试遗留的主题时，我还遇到了废弃的 Git Submodule（子模块）引发的底层版本树冲突。解决方式同样直接：使用 git rm -rf themes/blowfish 强制清除废弃模块及其索引。
最后，针对国内直连 GitHub 频繁超时的网络环境问题，在终端配置了本地代理路由：
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
至此，基础环境的排雷工作结束。写作环境和代码库在同一个物理目录下实现了逻辑隔离。下一步，就是如何把这份干净的代码推流上云，建立稳定的 CI/CD 自动化部署链路。
Comments & Reactions