01 · 整体概览：哲学与决策树
在动手之前，先想清楚要建一个什么样的东西、为什么这么选。
一、目标与边界
这套方法论解决什么问题？
把"零散的个人学习笔记" → 转化为"可分享、可长期维护、可扩展的主题型博客"。
不解决什么问题？
- ❌ 不是流量博客（不为 SEO 优化）
- ❌ 不是商业博客（不接广告/不带货）
- ❌ 不是协作博客（仅个人维护）
二、核心哲学
哲学 1：内容优先，工具靠边
第一阶段只写 markdown 文件——不装 git、不建仓库、不部署。先写够 3 篇有价值的内容，确认主题值得持续投入，再考虑技术栈。
反例：很多人花一周搭博客框架，一篇文章没写就放弃了。
哲学 2：一主题一仓库
不要做"我的所有笔记"这种巨型仓库。每个主题独立：
✅ 推荐
~/notes/
├── botc-learning-notes/ # 血染钟楼仓库 → 一个博客
├── reading-notes/ # 读书笔记仓库 → 另一个博客
└── tech-learning/ # 技术学习仓库 → 又一个博客
❌ 不推荐
~/all-my-notes/ # 大杂烩仓库
├── 血染钟楼/
├── 读书/
└── 技术/为什么独立：
- 每个主题可以独立演化——血染钟楼以后想加"实时推理工具"组件，技术博客可能想加代码示例渲染——两边互不干扰
- URL/域名独立——
botc.vercel.appvsreading.vercel.app，主题与品牌一致 - 仓库 commit 历史不被无关主题污染
哲学 3：源仓库与博客分离
源仓库（写 + 备份） 博客（展示 + 分享）
├── Gitee（中文圈） ├── Vercel CDN
└── GitHub（构建源） └── 自定义域名（可选）两者承担不同角色：
| 仓库 | 博客 |
|---|---|
| 文件名可以是中文 | URL 必须英文（分享友好） |
| README 是入口 | 首页 hero 是入口 |
| 直接看 markdown | 渲染过的网页 |
| 给开发者 / 自己看 | 给朋友 / 路人看 |
哲学 4：自动化优先
所有重复操作必须有 shell 函数封装——目标是"30 秒开一个新博客"。
bash
# 反面：每次都网页点击
打开 GitHub → New repo → 填名字 → 勾选 → 创建 → 复制 URL → 本地 add remote → push
# 正面：一行命令
github-init-and-push my-project "我的新项目"三、技术栈决策树
每一步都面临选择，下面是这次实践得出的"最佳路径"：
决策 1：源仓库托管在哪？
你需要给国内朋友分享 Markdown 文件吗？
├── 是 → Gitee（推荐，国内访问快）
│ + 同时 mirror 到 GitHub（用于 Vercel 构建）
└── 否 → 只用 GitHub这次我选：Gitee 主 + GitHub 镜像——因为想把仓库链接发给国内朋友。
决策 2：博客生成器选什么？
你的内容主要是什么？
├── 技术文档/学习笔记型 → VitePress（推荐，Vue 生态、清爽）
├── 个人随笔型 → Hexo / Hugo（社区大、主题多）
├── 重交互/动态 → Next.js（重，但什么都能做）
└── 极简静态 → 11ty / Astro这次我选：VitePress——内容是结构化笔记，VitePress 默认主题"左侧导航 + 右侧大纲"完美匹配。
决策 3：部署到哪？
你愿意 Mirror 到 GitHub 吗？
├── 愿意 → Cloudflare Pages（推荐，国内访问 + 免费 + 自动构建）
│ 或 Vercel（国际线路好，但国内需 VPN）
└── 不愿意 → 只有 Gitee Pages Pro（付费 + 备案）/ 自建 VPS这次我选：Cloudflare Pages——
- ✅ 国内裸连可访问（最关键）
- ✅ 完全免费 + 请求数无限
- ✅ 自动构建 + 自动 HTTPS
- ✅ Cloudflare Registrar 域名按成本价卖（如果以后想买域名）
💡 不推荐双部署：早期版本曾推荐 Cloudflare + Vercel 双部署作"国内国际兜底"，但实际维护增加心智成本——选一个 Cloudflare 已经够覆盖全球。
决策 4：URL 风格选什么？
源文件名要中文吗？
├── 是 → URL 用英文（rewrites 映射）
│ 源仓库友好 + 博客 URL 友好（推荐）
└── 否 → URL 直接用源文件名这次我选：双语策略 + rewrites——游戏复盘.md 在仓库里读起来友好，URL 重写到 /replays/001 在分享时友好。
决策 5：凭证管理怎么做？
你以后还会经常调 Gitee/GitHub API 吗？
├── 是 → ~/.config/{platform}/ 三件套（推荐）
│ token + user.env + 函数库 sourced from .zshrc
└── 否 → 一次性环境变量这次我选：长期凭证基础设施——封装 gitee-new-repo / github-init-and-push 等命令，以后再开主题用得着。
四、典型路径（如果一切顺利）
Day 0 本地写 3 篇内容验证主题
↓
Day 1 git init + 推到 GitHub（5 分钟）
↓
Day 1 装 VitePress + 配 sidebar（30 分钟）
↓
Day 1 在 Cloudflare Pages 接入 GitHub 仓库 + 拿到链接（5 分钟）
↓
Day 1 优化中文 URL → 英文 URL（10 分钟）
↓
完成：拿到 https://my-topic.pages.dev总耗时：1 个安静的下午。
五、典型坑（按出现顺序）
详见各阶段文档，这里是简版：
- npm 不接受中文项目名 →
package.json的name字段写英文 - VitePress 内部链接报死链 → 跨文件相对链接需要手动改成新 URL
- Cloudflare 默认 Node 版本太老 → 在环境变量里加
NODE_VERSION=20 - 构建输出目录 → 必须填
.vitepress/dist，不是dist - 微信里中文 URL 被 URL-encode 变丑 → 用 rewrites 把 URL 重写为英文路径
每一个都有解决方案，写在对应阶段文档里。
六、什么时候不用这套方法论
- 你的笔记不打算给别人看 → 直接用 Obsidian / Notion，不用搭博客
- 你的内容是 PDF / 视频为主 → 静态博客不合适
- 你想要复杂的动态功能（评论、用户系统、付费） → 用 Next.js + 后端
下一步
继续看 02-content.md 了解内容如何组织。