Cursor blinking
Blog

Vibe Coding 搭建个人博客网站记录

字数 3,941|阅读时长 ≈ 10 分钟

前言

为什么要自己做一个博客网站？

Notion + NotionNext 曾是我写博客的最优解。为了省点小钱，我在闲鱼上花几块钱买了个教育版邮箱升级 Notion；没想到前几天在公司电脑登录时，突然提示邮箱失效——心头一紧，当晚赶回家，趁家里电脑还在登录态，把所有笔记赶紧导了出来。

细算每月开销：Notion 订阅不算贵，但加上 VPN、Codex、Claude、DeepSeek、Seedance、Figma、云盘、网易云、芒果、Bilibili、微信读书……零零总总，实在不少。光是 Codex 每月就 $200。作为开发者，不自己折腾一个博客网站，多少有点说不过去。

更何况，在别人平台上写东西，你永远不知道明天会发生什么——算法变动、审核收紧，甚至平台关停，内容说没就没。Notion 用起来也并非处处顺心：经常闪回顶部；分块模式虽强，写作时却成了负担；阅读体验也不够纯粹。

事已至此，索性动手，开做自己的个人博客网站。

想做一个什么样的博客？

市面上现成的方案多如牛毛：WordPress 一键安装，Hugo / Hexo / Jekyll 等静态生成器，GitHub 上也不缺开源项目，随便挑一个半天就能上线。但它们的阅读与编辑体验，很难追上 Notion——而“改变习惯”，恰恰是最难的事。

我想要的个人博客网站，至少得满足这几点：

1. 看着要舒服

我对视觉没有太高的追求，但起码要“看起来自然”——字体、间距、颜色、留白，每一个细节都该和谐不突兀。

2. 写起来便利

写作体验一旦拉胯，本就不强的写作意愿只会更快被磨没，也更难养成持续输出的习惯。所以我需要一个能和现有工作流无缝衔接的方案——我已经习惯在 Notion 里写东西：桌面端尽量接近 Notion；手机端则更纯粹、更专注。底线是：能直接从 Notion 导出并生成博客内容。

3. 简洁为上

不要花哨背景，不要复杂交互，也不要各种社交嵌入。打开页面就是文章列表，点进去就能舒适阅读——仅此而已。编辑器也应该足够“透明”，让我忘记工具的存在，把注意力放回到“写什么”本身。

4. 小作坊，下猛料

在简洁之上，融入一些自己的想法：

  • 支持多种导入：Markdown、Notion URL、Notion ZIP 导出包、电子书（顺便把微信读书的会员也省了）；
  • 一键同步到掘金、知乎、小红书、公众号（一处编写，处处运行，让更多人看到）；
  • 后续可支持评论互动，以及方便收集喜欢的文章、图片；
  • 加入一点驱动力——阅读数、点赞数等反馈，能带来满足感，形成持续写作的正向循环。

5. AI 融合

自己的博客，天然适合和 AI 深度结合：可以预设偏好的文字风格与阅读模式；需要图片、表格、流程图、PPT 模板时让 AI 生成；甚至遇到新想法，直接让 AI 现场“打样”。这种专属感与操控感，是其他平台很难替代的。

说白了，我想要的就是一个有趣的、纯粹的、好读的、好写的个人专属博客网站。

大体思路

既然手里已经有 Notion 导出的数据，也有过接入 NotionNext 的经验，我的第一步很自然：让 AI 基于这些导出数据设计一套内容数据结构。它会成为“唯一真源”——导入要转成它，导出要基于它，展示也只是对它的呈现。

为了少走弯路，很多功能我直接对标现有编辑器：先把博客网站的基础能力跑通；再在真实使用中，把设计、功能、交互逐步往自己喜欢的方向打磨，持续完善这个产品。

接下来，进入 Vibe Coding 模式。

具体流程

一些准备工作

Codemarkdown
设备： mac设计工具： figma、make编码： vscode + codex 插件、codex app代码托管： codeup、codeup 流水线（部署）阿里云： ECS 服务器域名： notes.vectania.com（之前备案过的域名添加一个二级域名）

设计风格

我比较喜欢 Figma Make 生成的 UI 风格，经过多轮对话调整后，最终收敛到了这个博客网站的界面效果。

fig.1 博客网站整体 UI 效果
fig.1 博客网站整体 UI 效果

这里直接放出最终的 UI 结果，便于读者快速了解这个博客网站的整体样子和主要功能。

博客前台页面

fig.2 博客前台首页
fig.2 博客前台首页
fig.3 前台浏览器阅读设置
fig.3 前台浏览器阅读设置
fig.4 前台文章详情页
fig.4 前台文章详情页
fig.5 前台文章表格展示
fig.5 前台文章表格展示

博客后台页面

fig.6 后台首页
fig.6 后台首页
fig.7 后台同步管理页面
fig.7 后台同步管理页面
fig.8 后台中国访问数据看板
fig.8 后台中国访问数据看板
fig.9 后台文章元信息编辑页
fig.9 后台文章元信息编辑页
fig.10 后台导入文章弹窗
fig.10 后台导入文章弹窗
fig.11 后台全球访问数据看板
fig.11 后台全球访问数据看板

移动端页面

fig.12 移动端前台首页
fig.12 移动端前台首页
fig.13 移动端文章详情页
fig.13 移动端文章详情页
fig.14 移动端后台首页
fig.14 移动端后台首页

项目基础

我先用 Codex + GPT-5.5 做了一个 Demo：以 Notion 导出的数据为输入，参考 NotionNext 的文章展示思路，再结合 Figma Make 下载项目的视觉风格，先把技术方案写清楚，然后照着文档落地实现。第一版 Demo 就这样跑起来了。

预设规范

设计规范

为整个项目建立统一的 Design System。整体风格保持简洁、自然、克制，以内容优先。主题色仅使用黑、白、紫，以及它们不同透明度的颜色，或从黑→白、紫→白渐变中提取的颜色。这种配色方案类似 Android Material You 的动态色彩方案，便于后续开发多主题色功能。

采用 4px Grid 设计规范，所有小于 4px 的尺寸视为特殊情况（如 1px 边框），所有大于 4px 的尺寸（间距、图标、按钮、卡片、圆角等）均为 4 的倍数。

所有相同语义的组件必须保持统一，包括视觉样式、交互方式和状态反馈；按钮、Hover、高亮、Focus、Loading、鼠标样式等相似场景均应遵循一致的交互规则，确保整个项目具有统一的视觉语言和用户体验。

开发原则

核心思想是规则优先，避免不断堆叠 if else；该暴露问题就及时暴露，不要静默兜底，不要保留双路径。遵循 SOLID 原则，尽量分层、分模块、抽取公共类。日志统一输出，但要脱敏且不影响性能。小改动时编译要快，但不可出错。

项目架构

整个博客项目（开发）分为服务端、客户端（前台、后台），以及部分共享代码，是典型的 Web 应用架构。

fig.15 端侧分层架构图
fig.15 端侧分层架构图

文章的数据结构是一切的核心，导入、导出、展示、存储都围绕它展开。

fig.16 文章数据架构图
fig.16 文章数据架构图

文章内容达到一定量级后，架构便不可避免。类似 RecyclerView 只渲染当前窗口前后的块，配合懒加载、缩略图加载等策略解决超长文章的阅读体验问题。

fig.17 前台长文阅读渲染架构图
fig.17 前台长文阅读渲染架构图

再补一张编辑器架构图。编辑器的交互尤其复杂，要接近 Notion 的体验，其工作量大概是其他部分加起来的十倍还多。目前先实现了基础功能，等后续使用中再慢慢打磨。

fig.18 编辑器架构图
fig.18 编辑器架构图

Codex 配置

关于 Codex 配置，我单独整理了一篇教程 《Codex 使用简明教程——让 AI 真正帮你干活，而不是陪你绕圈》（由 AI 整理，我稍作修改）。最关键的是在项目根目录设置 Agent.md，明确告知 Agent 与我对话时先做什么、做完之后又该做什么。下面是我的 Agent 配置。

Codemarkdown
# Agent 工作约定 本文件适用于整个仓库。默认采用“轻前置 + 重后置”：开工前只看少量硬红线，避免方向性错误；完成后再按实际改动读取细则、验证并修正，避免每轮对话被规则文档淹没。 ## 工作流程 1. 开工前：读取本文件，判断任务类型和风险。简单问答、状态确认、纯评估不默认加载其他文档。2. 工作中：优先读代码事实和现有实现，沿用当前模块、命名、组件和数据流，不为了局部方便引入第二套路径。3. 交付前：按 `docs/Codex工作规则/交付校准与路由规则.md` 做后置校准；功能修改需要验收时，按 `docs/Codex工作规则/功能落地后自测和人工验收规则.md` 设计人工验收建议、补充或更新功能自测、确认运行态可直接验证；再根据实际触及范围补读相关文档、更新长期文档、运行最小必要验证。 如果文档和代码不一致，先判断代码是否已经成为新事实；是新事实就同步文档，不是新事实就修正实现。 ## 完成定义 - 代码、配置、脚本或文档结构变化，要说明实际改动范围和已运行的最小验证。- 用户可见功能、可复现 bug 或 UI 行为变化，要给出已验证 / 自测结果、人工验收建议、URL / 验收路径和剩余风险。- 未能运行应有验证或无法确认运行态时，要明确说明原因，不把静态检查描述成人工验收。- 交付前要确认没有违反前置硬红线；涉及本地记录、凭证、日志或外部服务时先脱敏。 ## 前置硬红线 - 客户端不能直接读写 SQLite；持久化写入必须经过服务端 API、迁移或明确的导入脚本。- 客户端前台只消费公开 payload；客户端后台只表达操作和临时状态，写入必须经过 admin API。- 服务端拥有事实、权限、校验、数据库写入和审计；HTTP 路由保持薄，业务逻辑进入 `server/src/modules`。- `shared` 只放跨端纯逻辑，不能访问数据库、文件系统、HTTP、DOM、cookie、localStorage 或环境变量。- FlowDocument 是正文唯一主协议；Markdown、HTML、外部平台格式和搜索索引都是导入边界、兼容输出或派生数据。- 日志和本地记录必须先脱敏；不要输出或写入 token、cookie、口令、私密正文、本机路径、私有远端或完整敏感 payload。 ## 按需读取入口 部分可复用流程已抽成 repo 级 Codex skills：`project-acceptance`、`project-commit-push`、`project-conversation-archive`、`project-ops-records`。skill 使用说明见 `docs/技术方案/Skill使用说明.md`。可用时可以用 skill 执行流程，但本文件、`docs/Codex工作规则/` 和本仓库架构文档仍是项目内最终约束；skill 不替代仓库硬红线和本地运维记录。 | 场景 | 读取文档 || --- | --- || 复杂、含糊、跨模块或高风险任务计划 | `PLANS.md` || 交付前校准、验证、文档更新判断 | `docs/Codex工作规则/交付校准与路由规则.md` || 开发原则、命名、验证、文档边界 | `docs/开发原则.md` || 功能修改后的人工验收建议、自测和运行态验证 | `docs/Codex工作规则/功能落地后自测和人工验收规则.md` || 提交、commit、push、提交所有未提交、排除本地杂项 | `docs/Codex工作规则/提交规则.md`；涉及远端、认证或凭证 helper 时同步读取 `docs/本地运维记录/代码提交与推送.md` || UI、移动端、阅读体验、弹窗、遮罩、布局、交互 | `docs/设计规范.md` || 服务端、客户端前台、客户端后台、shared 分层或数据流 | `docs/项目架构/项目架构.md`、`docs/项目架构/端侧分层架构.md` || 文章数据、数据库、公开 payload、后台 payload、搜索、导入、发布、同步 | `docs/项目架构/文章数据架构.md` || 编辑器、FlowDocument、事务、选区、拖拽、前台渲染协议 | `docs/项目架构/编辑器架构.md` || 对话归档、资源复制、session JSONL 摘要 | `docs/Codex工作规则/对话记录规则.md` || 服务器、Git、部署等反复使用的本地索引 | `docs/Codex工作规则/本地运维记录规则.md` | ## 本地记录 - 每次向用户交付最终回复前，按 `docs/Codex工作规则/对话记录规则.md` 把本轮可见对话归档到 `docs/对话记录/YYYYMMDD/`。- 用户添加的图片、视频、文档等资源，要同步复制到对应归档 Markdown 同名 `.assets/` 目录，记录里使用相对路径引用；图片资源要在资源行下方直接嵌入显示。- 连接服务器、推送代码、访问私有服务、部署脚本等反复使用的信息，按 `docs/Codex工作规则/本地运维记录规则.md` 记录到 `docs/本地运维记录/`。- `docs/对话记录/` 和 `docs/本地运维记录/` 是本地记录目录，默认不纳入 Git。

Agent 配置尤其要注意，信息过少，Agent 的回复就会缺乏规矩，导致后续纠偏任务繁重；信息过载则会增大上下文、拖慢响应，限制模型的创意。所以最佳策略是“轻前置 + 重后置”。

实际效果

比如下面这个日常对话

我：1. 标注显示有问题，且展开无内容，2. 图片没显示

fig.19 对话附图一
fig.19 对话附图一
fig.20 对话附图二
fig.20 对话附图二

Codex 回复：

Codemarkdown
已修好并上线，根因是 Notion URL 导入时没有补抓 toggle 子块，导致「思路」展开为空；同时 Notion 的 `attachment:` 图片没有先签名下载成本地公开资源，被 FlowDocument URL 清洗成了 `#`。 ## 已验证 / 自测结果 - 本地通过：  ```bash  npm run test:feature:notion-url-import  npm run client:type-check  PORT=7762 SERVER_PORT=7762 npm run server:check  git diff --check  ``` - 已提交并推送：  ```  3737d5f 修复 Notion URL 导入折叠和图片  ``` - 已部署生产：  ```  release 20260706-221822-3737d5f  ``` - 已回填线上原文章，保留原 URL / 发布状态；回填前已备份数据库：  ```  blog.sqlite.before-notion-url-repair-20260706-221929.sqlite  ``` - 公网 API 验证：  - `details=3`  - `思路 children=3`  - `media=18`  - 坏媒体 URL `0` - 公网页面 HTML 验证：  - 已包含 `bt-details-icon-text`  - 已包含 `/uploads/notion-url/`  - 没有 `attachment:`  - 没有 `#` 图片 URL - 第一张导入图片公网响应：  - `200 OK`  - `Content-Type: image/png` ## URL / 验收路径 文章页： https://notes.vectania.com/vibe-coding-搭建个人博客网站记录 ## 人工验收建议 用手机强刷这篇文章，检查顶部「💡 / 思路」区域展开后有内容；继续滑到图片段落，确认不再只显示文件名，图片能正常加载。 ## 剩余风险 我这里没跑真实浏览器自动化截图，因为当前仓库没有 Playwright；已用生产 API、SSR HTML 和图片资源 HTTP 响应做了运行态验证。本地还剩两个未跟踪 `.DS_Store`，未纳入提交。

按照规则，开始和结束任务后，大概要做这些事：

在 Codex 开始任务前

  • 先阅读 Agent.md，读红线，判断任务需不需读取更多细则

任务结束后，如果需要人工验收，进行下面这些

  • 基于开发原则、设计规范进行规范
  • 更新文档
  • 相关改动给出人工验收建议
  • 编写日常功能自测用例
  • 完成自测并给出自测报告路径
  • 准备好人工验收的环境
  • 剩余风险提醒
  • 记录这次的对话到“对话记录”文件夹下面
  • 如果有连接服务器、Figma、Notion 等操作，记录连接凭证，下次就不会再一通乱试
fig.21 任务对应的测试用例和报告
fig.21 任务对应的测试用例和报告
fig.22 记录每次对话和相关的 media 文件
fig.22 记录每次对话和相关的 media 文件

对于需要人工验收的任务，都会编写对应的测试用例。我把项目中的测试用例主要分为以下三类：

  • 日常开发：每次对话过程中产生的临时测试用例。
  • 专项测试：聚焦特定场景，例如超长文档的打开速度、快速滚动后的渲染表现等。
  • 日常巡检：涵盖功能主流程的测试用例（当积累到一定阶段时，可将“日常开发”中的用例汇总，生成工程主流程的巡检用例），也可用于深度全面的测试（如设置在凌晨定时自动执行的测试）。

此外，记录每一次对话，后续可交由 AI 进行分析，以识别其中重复或无效的交流，从而找出效率低下的原因，总结与 AI 沟通方式中的不当之处。

功能、体验、迭代

反复修改、持续迭代之后，这个博客网站乍一看已经“像那么回事”了；但一旦真正开始使用，就会发现：要做到“看着舒服”，其实非常难。字体怎么调都不顺眼，排版问题层出不穷：右侧文字对不齐、护眼模式下表格配色刺眼……这些细枝末节的麻烦，几乎没有尽头。

长文档的流畅性优化更像是在庞加莱圆盘里前进：越接近边界，走得越慢。即便花了很大力气，结果也未必令人满意。

如果说前期还算顺利，后期就很容易陷入泥潭。编辑器优化尤其折磨人，我很快就放弃了逐点微调——那更像是在消耗时间。于是我换了个问法：能不能把问题抽象成规则，让 AI 按我的设想自动完成？如果还是像过去那样死磕交互细节，引入 AI 又有什么意义？

即便有 AI 加持，开发效率确实提高了，但想做到“产品级”的体验——那种足以重塑用户习惯的层面——依然很难。

博客项目总结

token 使用情况

从 2026-06-29 到 2026-07-02，总计约 116,808,166 tokens。

会话日志部分为 112,657,323 tokens：input 111,602,902，output 449,368，reasoning output 170,870，cached input 102,246,784。cached input 是 input 的子集，无需额外相加。另有 4,150,843 tokens 只在运行日志中有总量记录，已计入总数。

代码行数

当前博客项目主代码规模约 5.6 万非空行；算上测试约 6.2 万非空行。

对话轮次

会话数：15

  • 用户输入：351 条
  • 完整对话文件：约 995 KB，24,434 行
  • 用户输入文件：约 97 KB，2,858 行

总结

关于 Vibe Coding

这个概念由 Andrej Karpathy 提出，本质是"跟着感觉走，忘掉代码的存在"——用自然语言告诉 AI 你想要什么，让它生成、迭代代码。我的整个博客项目，就是这么做出来的。 整个过程没有手写代码，也没有 Code Review。从汇编语言到 C++、Java、JavaScript，再到借助 AI 用自然语言编程——这条路在我看来是自然而然的进化。就像当年做安卓开发不必懂汇编一样，未来的开发者也完全不必死磕高级语言的细枝末节。 但很多人误解了 Vibe Coding，以为只是"让 AI 随便写"。其实不然。你需要清晰地知道自己想要什么、边界在哪、验收标准是什么。AI 是演奏者，你是指挥家——你要给出节奏、情绪和方向，否则再好的乐队也奏不出你想要的乐章。这就像《Fate/stay night》里圣杯战争最后的许愿环节——你不能以自己都不清楚的方式让圣杯实现愿望。

通用的东西要沉淀下来

开发过程中，好用的提示词、代码模块、工作流都值得记录。这次花两小时解决的问题，记下来下次只需两分钟。Don't repeat yourself——这是开发者最值得铭记的原则。 如果同样的事情做第二遍和第一遍花费的时间一样多，那不是勤奋，是愚蠢。

问题比答案更重要

在 Vibe Coding 的过程中，提出一个好问题往往比获得答案本身更具价值。好问题能引导 AI 生成更精准的方案，也能帮自己理清思路。编程的本质是思考，不是代码呈现，而问题能让人直面思考。在 AI 时代，更是如此。

放低预期

做这个博客项目不是为了完成什么 KPI，只是单纯想把一个东西做出来，于是就做了。过程中当然会遇到各种麻烦，所以我尽量保持一种“饱和式编程”的心态——不给自己设定“今天必须做完多少功能、必须发布多少篇文章”这样的硬指标。写博客不是为了“完成任务”，也不是为了追求完美；只要能通过这个博客网站，用自己的方式呈现想表达的内容，这本身就足够了。

从“需要”到“想要”

软件产品正从面向"需要"（需求驱动）转向面向"想要"（兴趣驱动）。未来会有越来越多的人，仅仅因为自己喜欢、觉得有趣，就去创造一些东西，释放自己的创意。

0