这篇文章想复盘的不是“如何初始化一个 Next.js 项目”，而是一个个人技术博客从能在本地跑起来，到真正拥有正式域名、搜索收录、分享预览、访问统计和稳定开发流程的过程。

网站是 https://xiaoyangren.me。它现在还不复杂，但已经不只是一个本地 demo：文章可以发布，页面可以访问，搜索引擎可以发现，链接分享有预览图，Vercel 能自动部署，也能看到访问和真实性能数据。

为什么要做这个博客

我最开始做这个博客，并不是为了造一个功能很多的平台。真正的动机很简单：我需要一个长期存放学习记录、算法题解、日记和个人知识管理内容的地方。

很多学习笔记如果只留在本地，很容易变成临时文件；如果只发在平台，又不完全属于自己。个人博客的意义在于，它既是一个展示入口，也是一个可以持续维护的知识仓库。文章、页面、样式、部署、域名和工作流都由自己掌控，后续想怎么演进也更自由。

所以这个项目一开始就没有追求复杂功能。我更关注几件事：

• 内容能稳定写入和展示。
• 页面结构足够清晰，后续可以扩展。
• 部署流程可靠，不依赖手动复制文件。
• 站点能被搜索、分享和监控。
• 开发过程能被记录下来，形成可复用的工作流。

这个目标决定了后面的技术选择和实现节奏：先让博客可用，再逐步让它更像一个正式网站。

技术选型：先选稳定的主线

当前项目使用 Next.js 16、React 19、TypeScript 和 Tailwind CSS 4。部署平台选择 Vercel，代码托管在 GitHub。

这个组合的优点很直接：Next.js App Router 适合做静态页面和博客路由，Vercel 对 Next.js 的支持也足够顺滑。对个人项目来说，这种“框架和部署平台相互配合”的体验很重要，因为我不想把大量时间花在构建脚本、服务器配置和发布流程上。

TypeScript 提供了基本的类型约束，适合在项目不断加功能时保持边界清晰。Tailwind CSS 则让我可以快速调整页面风格，但它也有副作用：如果没有设计约束，很容易堆出一堆看起来像模板的卡片和按钮。后面我专门补了 docs/design.md，也是因为这个问题。

内容系统没有直接上 CMS，也没有引入 MDX。文章放在 content/posts/*.md，通过本地 Markdown 文件维护。这个选择很朴素，但对当前阶段最合适：文章数量不多，内容由我自己维护，本地文件已经足够稳定。

Markdown 内容系统

文章系统的核心思路是：Markdown 文件只负责内容，页面组件只负责展示，读取和转换逻辑集中在 src/lib/posts.ts。

每篇文章都有 frontmatter：

---
title: "文章标题"
excerpt: "文章摘要"
date: "YYYY-MM-DD"
tag: "项目实践"
---

文件名生成 slug，frontmatter 提供标题、摘要、日期和标签，正文通过 remark、remark-gfm 和 remark-html 转成 HTML。这样 /posts 可以展示文章列表，/posts/[slug] 可以展示详情页，标签页和归档页也可以复用同一份文章数据。

后面我又补了字数统计。这个功能没有做成预计阅读时间，因为技术文档、算法题解和学习笔记的理解成本不只取决于字数。最后的选择是只展示“约 N 字”，让读者知道文章大概体量，但不暗示几分钟能读完。

这个阶段的经验是：个人博客的数据层不一定要复杂，但口径要统一。列表页、详情页、标签页和归档页都应该从同一个读取函数拿数据，否则后续很容易出现排序、字段或统计口径不一致。

页面从可用到像个人网站

最初的页面只需要能导航、能展示文章。但真正上线前，我发现“能用”和“像一个个人网站”之间还有明显差距。

首页需要表达站点是谁的、写什么、最近有什么内容。文章列表需要搜索和标签筛选。标签页负责按主题聚合，归档页负责按时间回看，About 页面则承担真实个人介绍和联系方式。后来我还补了 GitHub、邮箱、Codeforces 和牛客信息，让这个网站不再像一个空模板。

视觉上也经历了几轮调整。首页第一版 polish 后，结构还带着比较明显的模板感：入口卡片权重接近，最新文章像等分组件。后来我把首页重新整理成更明确的内容入口：/posts 是主入口，/tags、/archive、/about 是次级入口；最新文章也从三张等高卡片调整成一篇重点文章加两篇轻量文章。

文章详情页的重点则是阅读体验。长文题解需要目录、合适的正文宽度、清楚的 h2 / h3 层级、代码块和表格滚动，以及不抢占阅读区域的浮动 TOC。移动端目录也不能占满首屏，所以后来改成折叠目录。

这些调整没有改变业务逻辑，但它们决定了这个博客是否愿意被长期阅读。

GitHub + Vercel 部署闭环

部署选择 GitHub + Vercel。代码推到 GitHub，Vercel 绑定仓库后监听 main 分支，后续 push 就会自动部署。

这个流程看起来简单，但实际过程中还是遇到了一些问题。比如 GitHub push 时出现过 HTTPS/TLS 握手失败，这类问题最后并不是代码错误，而是本地网络和代理环境导致的。处理方式不是乱改 remote，也不是强推，而是先确认错误类型，再用代理重试。

Vercel 绑定 GitHub 时也遇到过认证相关问题。这个部分不适合写账号细节，但经验是：部署平台、代码平台和本地 Git 三者要分开排查。代码能 build，不代表仓库绑定一定正常；GitHub 能 push，也不代表 Vercel 已经有权限拉取。

每次提交前我都会做几件事：

npm run lint
npm run build
git status --short --untracked-files=all
git diff

这些命令不复杂，但它们能防止很多低级问题：未提交文件、意外改动、构建失败、类型错误和样式验证遗漏。

域名配置：从能访问到正式入口

博客最终绑定到 xiaoyangren.me，域名在阿里云购买，部署托管在 Vercel。

域名这一步让我再次意识到，网站上线不是只点一个 Deploy 按钮。域名购买后还涉及实名认证等待、DNS 解析配置、Vercel 域名绑定、主域名和 www 的关系处理。现在的结果是 https://xiaoyangren.me 作为主入口，https://www.xiaoyangren.me 重定向到主域名。

这里最需要耐心的是 DNS 生效和平台状态同步。很多时候不是配置错了，而是解析、认证或证书状态还没完成。这个阶段不要频繁乱改记录，也不要把验证记录、后台截图和账号信息写进公开文章。公开复盘只需要记录处理思路，不需要暴露完整后台细节。

SEO 与分享：让网站能被发现

上线后，如果搜索引擎不知道这个站点存在，链接分享也没有正常预览，那它仍然只是一个可以访问的页面集合。

我先补了站点级 metadata，包括 title、description、authors、keywords、metadataBase、canonical、Open Graph 和 Twitter card。后来又给文章详情页加了独立 metadata，让每篇文章都使用自己的 title、excerpt、slug、date 和 tag。

接着新增了 sitemap.ts 和 robots.ts。sitemap 包含首页、文章列表、标签页、归档页、About 页和所有文章详情页；robots 允许抓取，并指向正式 sitemap 地址。这个配置完成后，就可以去 Google Search Console 添加资源、验证域名所有权并提交 sitemap。

分享图也是一个小但重要的细节。我做了站点级 Open Graph / Twitter 图片。第一版图排版不满意：Yang 标识挤在一起，标题安全边距不足，外框像模板卡片。后来重新调整成更克制的版式：纯白背景、细线、充足留白、小型 Yang 标识和站点标题。

这一步的收获是：SEO 不只是写几个 meta 标签，分享预览也不只是“有图就行”。标题、摘要、canonical、sitemap、robots、文章级 metadata 和 OG 图要形成一套完整的入口体验。

Codex 工作流：让 AI 参与闭环，而不是替代判断

这个项目很大一部分工作是和 Codex 协作完成的。真正重要的不是“让 AI 写代码”，而是把 AI 放进一个受约束、可验证的工程流程里。

我先写了 AGENTS.md，记录项目背景、技术栈、目录结构、Markdown 文章系统、安全边界、开发命令和 Git 规则。这样每次让 Codex 做事时，它不是在空白环境里猜项目规范。

后来又补了 docs/codex-workflow.md，把常见工作流拆成计划、实现、验证、提交几个阶段。小任务可以直接闭环，大任务先出计划再实施。提交前必须看 git status 和 git diff，涉及 UI 的改动要用 Playwright MCP 做只读检查。

docs/design.md 是后面才加的。原因很现实：Codex 做 UI 时第一版经常“能用但审美普通”，容易出现模板感、卡片堆叠和无意义装饰。设计规范明确了这个博客要走极简技术风，white / zinc / black 为主，orange 只做少量点缀，动效要克制，不能影响阅读。

Context7 MCP 用来查 Next.js、Vercel、Metadata API 这类版本敏感文档，避免只凭记忆改 API。Playwright MCP 用来验证页面加载、交互、TOC、details/summary、响应式和水平溢出。Impeccable Skill 则用于 UI polish 和设计审查，但它不能替代 docs/design.md。

这套工作流的核心是：AI 可以提出方案、实现代码、执行检查，但最终仍然要由项目规则、运行结果和人的审美判断共同约束。

踩坑记录

这个项目遇到的问题并不罕见，但它们很适合作为个人项目上线的提醒。

GitHub push 出现 HTTPS/TLS 握手失败时，第一反应不应该是改代码。更合理的判断是：如果本地提交正常、remote 正常、错误集中在网络握手，就先按网络或代理问题处理。

Vercel GitHub 绑定认证问题也类似。部署失败不一定是项目 build 失败，可能是平台授权、仓库访问权限或账号状态。排查时要先确认失败发生在哪一层。

Next.js build 过程中也遇到过 Google Fonts 访问失败。错误指向 next/font/google 时，不能马上把字体方案删掉。这个项目后来把处理规则写进了 AGENTS.md：先判断是否是 Google Fonts 网络问题，再用临时代理重试；如果仍失败，再等待确认，不要擅自改 layout。

域名配置阶段的问题主要是等待和状态同步。实名认证、DNS 生效、证书签发和 Vercel 状态更新都有延迟，不能每隔几分钟就推翻前一次配置。

还有一次 hydration mismatch 来自浏览器插件干扰。这个问题提醒我：本地浏览器环境也可能制造假象。遇到前后端渲染不一致时，除了看代码，也要考虑插件、缓存和扩展脚本。

OG 图返工则是视觉层面的教训。资源文件不是生成出来就结束，尤其是分享图这种会被放在聊天软件、搜索结果或社交平台里的入口资产，必须检查排版、边距、裁切和小尺寸识别度。

当前不足和后续计划

现在这个博客已经完成了第一阶段上线闭环，但它还只是 MVP。

内容上，文章数量还少，后续需要持续写技术笔记、算法题解和复盘。页面上，首页和文章详情页已经做过 polish，但标签页、归档页和 About 页还有继续统一细节的空间。

功能上，之后可以考虑评论、草稿、文章系列、站内搜索、动态 OG 图、更多可视化统计和更完整的设计系统。但这些都不是当前最急的事。对个人博客来说，最重要的仍然是稳定写作和持续维护。

我也不急着把它变成一个复杂平台。这个项目的价值在于，它已经把内容系统、部署、域名、SEO、分享、监控和工作流串起来了。后面的每一次改动，都可以在这个闭环上继续迭代。

最后的收获

从这次项目里我最大的感受是：个人博客真正的难点不在于把页面写出来，而在于把所有看似零散的环节连接起来。

Next.js 负责页面和内容，GitHub 负责版本管理，Vercel 负责部署，阿里云域名提供正式入口，SEO 和 Search Console 让站点被发现，OG 图让链接分享更完整，Analytics 和 Speed Insights 让上线后的状态可见，Codex 工作流则帮助我把每一步变得可验证。

这也是为什么我把它称为“上线复盘”，而不是“搭建教程”。搭建只是开始，上线闭环才是这个项目真正完成的第一阶段。