前段时间给自己换博客系统试了一圈发现要么太重、要么太花哨直到看见 T3。严格说 T3 是一个开源的个人博客方案它的核心思路很直接文章是文本文件躺在 GitHub 仓库里线上站点由 Vercel 自动构建部署。没有后台管理界面、没有数据库写博客变成了“管理一批 Markdown 文件”这件事本身。T3 的前身叫 Textarea作者是 Vercel 的知名工程师 Shu所以底层技术选型非常现代原生支持公式、代码高亮、交互组件这些写作刚需。如果你和我一样需要的是一个足够安静、足够专注的写作空间同时又不排斥自己动手折腾一点配置那这篇文章应该正好对口。1. 为什么是 T3一个“反直觉”的博客选择1.1 先梳理一下市面上的博客方案这两三年我陆续试过不少方案大体上分成三类。第一类是传统动态博客典型代表是 WordPress、Ghost。功能确实全插件生态也丰富但要维护服务器、数据库、定期备份一不小心就变成了“给系统升级本身写文章”。我身边不少人最后博客停更的原因不是没素材而是后台崩了或者环境升级搞坏了。第二类是静态站点生成器Hugo、Hexo、Astro 这类。它们把文章渲染成纯静态页面速度快部署也简单但使用起来有一道不算低的学习门槛你得先理解主题、布局、模板、构建流程这些概念。经常是文章还没写几篇先花了两周调主题样式。第三类就是基于 Next.js 这类框架的“全栈轻量博客”T3 正好落在这里。它没有独立的后台却也不是纯静态生成——它使用 Next.js 的构建与渲染能力把仓库里的文本实时变成站点页面。说白了它是给了你一个现代前端框架做好的“半成品”你只需要往里填内容。1.2 T3 到底解决了什么问题我觉得 T3 解决的是“写作与发布之间的割裂感”。回想用传统后台写东西的流程打开后台、新建文章、排版、插图片、点发布。每一步都在一个封闭界面上完成思路很容易断。而用 T3 的流程是在本地编辑器里写一个.md文件写完了git push站点自动更新。不需要打开任何管理后台不需要填写摘要和 SEO 信息其实 T3 会从正文里自动提取这些。这个“把写作还给文本编辑器”的设计对我来说非常受用。我平时用 VS Code 写代码也用 Typora 做笔记写博客时同样是在编辑器里完成没有任何切换成本。而且由于内容是纯文本文件我可以轻松地做版本管理、全局搜索甚至写脚本批量调整格式。这些都是传统后台很难给到的自由。还有一个很实际的好处内容的所有权完全在你手里。仓库里的 Markdown 文件就是全部资产什么时候不想用 T3 了换任何一个能解析 Markdown 的系统都能平滑迁移。不会出现“博客数据锁在平台里”的尴尬。1.3 适合谁不适合谁先说适合谁如果你平时已经在用 GitHub对 Git 的基本操作不陌生想要一个界面干净、载入快、让你更专注于文字本身的博客T3 会非常合适。再宽松一点说即使你只是能用 Git 做 push 和 commit剩下的交给模板和平台自动化也足够了。不适合的场景也有。如果你需要复杂的数据结构比如多级分类、动态目录树、每篇文章独立浏览量统计T3 这种极简路线会需要你自己去加代码体验上不一定划算。另外如果你完全不想接触任何命令行操作就想打开网页填个标题点发布那还是传统后台方案更顺手。T3 的定位一直很明确给愿意掌控自己的内容的写作者用不是给“一切帮我代劳”的用户用。2. 从零搭建仓库结构、本地环境与写作流2.1 准备一个仓库T3 的部署方式决定了你首先要有一个 Git 仓库。我建议直接用它的模板仓库来初始化而不是从零手写因为项目里已经包含了一整套内容目录、样式文件和构建配置省去大量起步工作。初始化时章鱼副歌分两步进入 T3 的 GitHub 页面使用模板创建你自己的仓库命名比如my-blog。把仓库克隆到本地git clone gitgithub.com:你的用户名/my-blog.git。之后所有操作都围绕这个本地仓库进行。你需要装的只有 Node.js 和包管理器npm 或 pnpm。Node 版本建议选 LTS 版本避免某些编译依赖在过旧版本上报错。依赖安装我用的是 pnpm原因很简单T3 项目本身依赖较多pnpm 的硬链接机制能省不少磁盘空间安装速度也快。命令行只有一句话pnpm install装完直接pnpm dev本地服务默认跑在localhost:3000。打开浏览器看到默认首页说明环境没问题可以开始往里写内容了。2.2 目录结构与内容组织T3 的内容组织方式很有代表性。项目里有一个专门的content目录所有文章按年份或主题分子目录存放这个划分逻辑是模板自带的你也可以改成自己喜欢的方式。我的目录是这样的content/ ├── posts/ │ ├── 2024/ │ │ ├── 01-初识-t3.md │ │ └── 02-博客部署.md │ └── 2025/ │ └── 01-写作流程复盘.mdx └── pages/ ├── about.md └── uses.mdposts放正式文章pages放固定页面比如“关于我”。T3 会递归扫描整个content目录你不需要主动注册任何路由文件放进去、推上去页面就有了。这个设计很符合直觉——你在文件系统里如何组织文章在站点上就会如何呈现。文件名我习惯用日期-英文短横线标题格式。日期信息在文件名里保留一份后面做归档排序时非常方便。中文长标题放在文件内容里作为 Frontmatter 的title字段这样 URL 保持简洁可靠页面的显示标题又不受影响。2.3 Frontmatter 与写作规范每一篇文章的开头都有一小段 YAML 格式的元信息T3 靠它识别标题、日期、摘要和标签。我常用的字段是这几个--- title: 用 T3 搭建个人博客的完整记录 date: 2025-01-12 summary: 从仓库初始化到部署上线的全过程包含踩坑记录。 tags: [博客, Next.js, 写作] ---有几个字段的作用值得展开说summary是我强烈建议大家写的字段。T3 在列表页和社交媒体卡片里都会用到它。如果留空系统会自动截取正文前几个字符但自动截取往往在语义上不够准确自己想一句摘要表达会更精准别人也更容易判断值不值得点进来。tags用来组织文章。T3 的标签页会把所有标签聚合成一个页面点击某个标签能看到所有打上该标签的文章。标签命名上我吃过亏一开始随手写了大小写不同但含义相同的词比如“Nextjs”和“Next.js”后来标签页里同一个主题被拆成了两堆。后来我统一成小写加连字符的风格比如nextjs、markdown再没出过这个问题。Frontmatter 之外还有一个小设置很容易忽略draft字段。写草稿的时候把它设成trueT3 会自动跳过渲染本地却仍然可以看到预览。我在每次发布前会单独跑一遍文章列表检查确认没有残留的草稿标记。3. 部署上线Vercel 构建、环境变量与域名3.1 Vercel 导入项目的完整流程T3 的部署我直接用的 Vercel这是跟 Next.js 同源的最顺滑方案。把仓库推送到 GitHub 之后登录 Vercel 控制台点击“Add New Project”选择你的博客仓库剩下的交给平台就行。整个流程里有一个关键点容易被新手忽略框架预设。Vercel 会自动识别 Next.js并把构建命令设置为next build。我建议在导入时把框架预设确认一下因为有些仓库会不小心被识别成其他框架。识别错误的话构建大概率会失败而且失败日志对小白来说并不友好。导入页面里不用特意改任何构建参数默认的npm run build或 pnpm 对应的 build就能通过。点击 Deploy 后第一次构建会跑 3 到 5 分钟看网络情况。数秒后你会收到一个默认的.vercel.app域名站点已经可以直接访问了。等这个域名能打开就说明从仓库到线上这条链路已经打通。3.2 环境变量与构建配置很多网友以为 T3 部署完就完事了但实际上有些功能需要环境变量才能启用。最典型的是“文章增量更新”相关的机制需要配置 GitHub Token这样站点构建时才能自动拉取最新的内容提交。环境变量的配置路径是 Vercel 项目设置里的Environment Variables页面。我配置的变量结构大致是名称 值 TOKEN ghp_你的GitHub个人访问令牌这个 Token 在 GitHub 个人设置里生成理论上给repo相关权限就够了。生成之后你可以自己在本地用一行命令测试它是否有权限访问目标仓库curl -H Authorization: token 你的TOKEN https://api.github.com/repos/你的用户名/my-blog返回正常 JSON 说明权限没问题。“能用”和“好用”之间往往就差这一个看似多余的验证步骤省得部署完发现功能异常还得回头查权限。3.3 自定义域名与 HTTPS默认的vercel.app域名适合临时体验正式写博客我建议绑定自己的域名体验和可维护性都会好很多。绑定流程简单说三步在 Vercel 项目的 Domains 里填入你的域名到域名服务商那边按提示添加一条 CNAME 记录指向 Vercel 给的地址通常是cname.vercel-dns.com保存之后等待几分钟Vercel 会自动申请和续期 HTTPS 证书。整个过程不需要自己手动上传证书这是托管平台最大的省心之处。需要注意的是如果你用的是国内域名服务商DNS 解析记录生效可能需要更长时间有时候要半小时以上不要急着一分钟刷新几十次。我当时的做法是先去泡杯茶过几分钟再回来看通常就绿了。4. 写作体验进阶MDX、公式、代码高亮与组件4.1 Markdown 之外的 MDXT3 不只是支持普通 Markdown还支持 MDX。MDX 简单说就是在 Markdown 里可以直接嵌入 React 组件。这让一篇博客文章不光是静态文字还能具备交互能力。举个实际例子如果你写一篇关于某种算法的文章普通 Markdown 只能展示代码块和文字而 MDX 可以内嵌一个可交互的演示组件——比如一个滑块读者拖动就能看到不同参数下的运行效果。这在技术博客里带来的阅读体验提升远比截图和文字描述强。我自己的用法相对保守最常用的是把一些固定的排版模块封装成组件然后在文章里调用。比如“提示框”和“参考资料”这两个组件我用在多数技术文章里。写法类似import Callout from components/callout; Callout typewarning 这段代码依赖 Node 18 以上环境低版本会导致启动失败。 /Callout这样每次要写提示时不用重复排版而且全站风格保持一致。T3 的组件位置放得比较清晰按作者的仓库目录结构放就能被 MDX 解析器找到。4.2 LaTeX 公式与代码高亮技术博客绕不开数学公式。T3 对 LaTeX 的支持开箱即用行内公式用$...$块级公式用$$...$$。我写一些带复杂度推导的文章时不用切任何编辑器直接在 Markdown 文件里写公式最终渲染的效果和学术论文差不太多。举一个最常见的使用场景。在文章中写行内公式梯度下降的更新规则是 $θ : θ - α \cdot \nabla J(θ)$其中 α 是学习率。渲染出来就是一个干净的数学表达式不用去生成公式图片再引用维护起来也方便得多——文本文件里要改公式就是直接改那几个字符。代码高亮同样是搭建完就有的能力。它支持常见的语言标注比如const greeting (name) Hello, ${name};T3 会把代码块渲染成带行号和高亮的样式某些语言的关键字颜色区分很清楚。我特别满意的是它对长代码的换行处理不像有些博客系统那样把横条拉得老长而是过度长代码自动换行移动端阅读体验友好。4.3 摘要、标签与 SEO 细节前面提到 Frontmatter 里的summary字段它在 SEO 层面的价值比我们想象中还大因为它不仅出现在文章列表页还会成为社交分享卡片里的描述文本。我在各地群分享文章链接时别人看到的那段简介就是我写的 summary而不是系统乱抓的正文首句。自从我把每篇摘要用心写之后从第三方平台跳转过来的阅读量有明显变化。T3 对每个标签会自动生成一个页面这个功能对内容沉淀很有益。读者读完一篇文章顺着标签能继续找到同一主题的其他文章停留时间会显著变长。我在部署前原本打算自己写标签聚合页后来发现 T3 已内置了支持省了一大截开发量。SEO 的另一块是小细节站点的元信息比如 title、description、favicon。T3 的配置文件里留好了统一入口不用到每个页面去改。我把自己的站点描述从默认文案改成一句话定位后搜索引擎抓取到的摘要信息就变得准确多了。这件事做在写第一篇文章前后面所有页面的元信息都能自动带上这些基础设置。4.4 为文章设置正确的写作环境本地写作有一个非常容易被忽视的问题Markdown 的换行和空格细节。默认 Markdown 规则里换行不一定等于段落的拆分你需要在行尾加两个空格或者留一个空行段落之间才会正确分开。我在刚开始写作时很不习惯写完总是显示成一个巨大的文本块。后来我统一了做法每个段落之间绝对留一个空行段落内部绝不打两个多余空格。这样不管在什么 Markdown 渲染器里看排版都不会乱。还有个细节是中文引号。我平时写代码习惯了 ASCII 环境写文章时打引号会直接用半角双引号结果在页面里看着非常别扭跟中文内容格格不入。后来我在本地装了一个自动把半角引号转成全角引号的小工具写完后统一跑一遍转换视觉上立刻自然很多。这类“编辑器层面的小设定”对人阅读体验的影响常被写博客的人忽略。5. 踩坑记录我从“能用”到“好用”的排查过程5.1 坑一改了文章线上却看不到更新第一次遇到这个问题是在上线最初几天。我在本地改了文章标题推送到 GitHubVercel 的构建日志里显示部署成功了但打开线上页面看到的还是旧标题刷新多少遍都不变。我一开始以为是缓存问题在浏览器里清空缓存重试没有变化。后来把范围缩小到Vercel 构建成功、线上静态资源也更新了那变数很可能在数据源。排查发现我的仓库确实收到了提交记录但 T3 在构建时拉取内容依赖那个 GitHub Token 的权限配置而我当时根本没有配置这个环境变量导致构建时没有读取到最新的提交而是用本地缓存的数据。找到根因后我做了两件事第一在 Vercel 里配置好具有正确权限的 Token第二重新触发一次部署。这次打开页面新标题正常显示。从此之后我每次提交后会在 Vercel 构建日志里确认它有没有执行“内容拉取”这一步有就放心了没有再发生过同类问题。5.2 坑二图片路径本地与线上不一致写文章时插入图片用的是相对路径本地预览正常部署到线上后却发现图片裂了。这个问题很典型原因在于本地开发时文件的物理路径与线上构建后的静态资源路径不完全相同。我的图片是放在文章同级的目录里的文章引用的方式是./images/流程图.png。本地预览时Markdown 解析器能找到相对路径但部署阶段T3 会把 Markdown 内容映射到站点的 URL 体系里相对路径就变成了相对于当前路由。如果文章路由是/posts/2024/01-初识-t3那么./images/流程图.png会被解析成/posts/2024/01-初识-t3/images/流程图.png这显然不对。后来我改用公共资源目录方案把图片统一放在项目的public目录下的images/posts/xxx/文件夹里文章里直接写绝对路径/images/posts/xxx/流程图.png。这样无论本地还是线上路径都指向同一个位置不再依赖于文章的物理位置。5.3 坑三代码块里的特殊符号被吞掉某次写一篇讲命令行工具的教程代码块里有一行$echo $HOME类似的内容渲染出来总是少字符。开始我以为是自己手误关掉自动格式化后才发现问题出在 Markdown 解析时的字符转义。在 Markdown 的某些解析规则里字符与特殊格式可以共存也会冲突。尤其是用到*、_、反引号这些与 Markdown 语法冲突的字符如果不加注意渲染结果就会异常。我的解决方法是代码块的语言标注一定写准确不写语言或者标错语言解析器会启用不同的高亮处理逻辑而有些高亮逻辑对特殊字符转义是双重的。现在我在代码块里只使用明确标注语言的方式遇到冲突字符时优先用 HTML 实体编码而不是硬写原文。这个方法在大多数渲染场景下都稳。5.4 一个小坑修改 Frontmatter 导致文章渲染失败有次我把摘要写得太长超过了从某个字符开始的部分页面直接报错。排查下来是 YAML 的解析问题——摘要里包含了一个冒号而我没有用引号把它包起来YAML 解析器把冒号后面的内容当成了嵌套结构。从那以后Frontmatter 里的所有字段值我统一用引号包裹特别是标题和摘要这类容易出现带标点内容的地方。用引号包裹之后冒号、感叹号、特殊符号都不会再影响解析。这个习惯后来帮我避免了很多麻烦包括发出去的定时任务和脚本在读取 Frontmatter 时也都能正确解析。5.5 盘点一下“本地正常、线上异常”这类问题这类问题排查时我总结了一条顺口溜先看构建日志再看环境变量最后怀疑路径和缓存。顺序很重要构建日志确认线上代码确实更新到了最新版本。环境变量确认与 GitHub 交互的凭证、自定义变量都配好了。路径确认所有静态资源的引用方式在构建产物里依然有效。缓存确认 CDN 和浏览器缓存没有把旧版本锁住。按照这个顺序排查绝大多数“本地正常线上异常”的问题都能在十分钟内定位。6. 写作习惯的变化与值得做的扩展6.1 写作习惯的变化用了 T3 之后我的写作习惯发生了两个明显变化。一个是从“后台打字”变成了“编辑器写作”。过去用后台时我总想开着网页直接写写到一半又忍不住去看排版效果。现在我在本地编辑器里写眼睛盯住文字本身排版效果反而没那么在意了。这个变化让我写完整篇初稿再一次性发布的频率大大提高。另一个变化是“提交频率”显著变高。以前写完文章是一次性保存现在写完一个小节就 commit 一次把文档写成一种“版本化日志”。好处很明显写坏了可以回退到任何一个历史版本写不下去时重新读历史 commit 能快速找到思路。我强烈建议写长篇技术博客的朋友养成这个习惯成本极低收益却非常实在。6.2 值得做的扩展方向T3 默认是够用的但如果你愿意稍微折腾有几个方向很值得做。第一个是评论系统。T3 本身不带评论区我集成了一个基于 GitHub Issue 的评论方案读者评论时本质上是在文章对应的 Issue 里留言。这个方案有一个我不太喜欢的点是不是每个读者都有 GitHub 账号会挡掉一部分想评论的人。但它胜在零服务端成本、内容可控而且跟“内容存在 GitHub 上”的整体思路完全一致。第二个方向是接入第三方的浏览量统计。T3 是纯前端项目加统计脚本非常方便。我在全局布局里注入了一段统计代码只统计页面级事件。这里提醒一句接入统计时尽量绕开与用户身份强绑定的方案毕竟博客是公开内容保留访客的基本隐私对读者的体验更友好。第三个方向是内容形态的扩展。T3 既然支持 MDX我后来把一些“半成品”的交互演示做成了文章内的内嵌组件比如一些简单算法的可视化。读者看文章的时候可以直接拖动参数观察结果变化这种内容的去留往往决定一篇技术博客是否被收藏。目前我通常只给重点文章加这个待遇因为开发成本还是在的。6.3 我现在的日常发布流程最后分享我的标准流程非常简单一眼看完在content/posts/下新建文件写好 Frontmatter。写作过程中写一段就git commit一次。全文写完检查一遍 summary 和 tag确认无草稿标记。git push等 Vercel 构建完成后确认页面更新。整套流程从写完到发布人类操作大约一分钟。这份“无摩擦”的体验是 T3 给我最强烈的感受。它让我愿意多写、常更而不再把发博客当成一项要跨过很多步骤的麻烦事。我也说说个人体会博客这件事工具不必多够纯粹就好。T3 通过把复杂的发布流程简化成“提交文件”帮我腾出了原本浪费在后台和插件上的精力全部放回文字本身。如果你的目标也是认真写点东西这套方案值得你花半天时间折腾一下。
前段时间给自己换博客系统试了一圈发现要么太重、要么太花哨直到看见 T3。严格说 T3 是一个开源的个人博客方案它的核心思路很直接文章是文本文件躺在 GitHub 仓库里线上站点由 Vercel 自动构建部署。没有后台管理界面、没有数据库写博客变成了“管理一批 Markdown 文件”这件事本身。T3 的前身叫 Textarea作者是 Vercel 的知名工程师 Shu所以底层技术选型非常现代原生支持公式、代码高亮、交互组件这些写作刚需。如果你和我一样需要的是一个足够安静、足够专注的写作空间同时又不排斥自己动手折腾一点配置那这篇文章应该正好对口。1. 为什么是 T3一个“反直觉”的博客选择1.1 先梳理一下市面上的博客方案这两三年我陆续试过不少方案大体上分成三类。第一类是传统动态博客典型代表是 WordPress、Ghost。功能确实全插件生态也丰富但要维护服务器、数据库、定期备份一不小心就变成了“给系统升级本身写文章”。我身边不少人最后博客停更的原因不是没素材而是后台崩了或者环境升级搞坏了。第二类是静态站点生成器Hugo、Hexo、Astro 这类。它们把文章渲染成纯静态页面速度快部署也简单但使用起来有一道不算低的学习门槛你得先理解主题、布局、模板、构建流程这些概念。经常是文章还没写几篇先花了两周调主题样式。第三类就是基于 Next.js 这类框架的“全栈轻量博客”T3 正好落在这里。它没有独立的后台却也不是纯静态生成——它使用 Next.js 的构建与渲染能力把仓库里的文本实时变成站点页面。说白了它是给了你一个现代前端框架做好的“半成品”你只需要往里填内容。1.2 T3 到底解决了什么问题我觉得 T3 解决的是“写作与发布之间的割裂感”。回想用传统后台写东西的流程打开后台、新建文章、排版、插图片、点发布。每一步都在一个封闭界面上完成思路很容易断。而用 T3 的流程是在本地编辑器里写一个.md文件写完了git push站点自动更新。不需要打开任何管理后台不需要填写摘要和 SEO 信息其实 T3 会从正文里自动提取这些。这个“把写作还给文本编辑器”的设计对我来说非常受用。我平时用 VS Code 写代码也用 Typora 做笔记写博客时同样是在编辑器里完成没有任何切换成本。而且由于内容是纯文本文件我可以轻松地做版本管理、全局搜索甚至写脚本批量调整格式。这些都是传统后台很难给到的自由。还有一个很实际的好处内容的所有权完全在你手里。仓库里的 Markdown 文件就是全部资产什么时候不想用 T3 了换任何一个能解析 Markdown 的系统都能平滑迁移。不会出现“博客数据锁在平台里”的尴尬。1.3 适合谁不适合谁先说适合谁如果你平时已经在用 GitHub对 Git 的基本操作不陌生想要一个界面干净、载入快、让你更专注于文字本身的博客T3 会非常合适。再宽松一点说即使你只是能用 Git 做 push 和 commit剩下的交给模板和平台自动化也足够了。不适合的场景也有。如果你需要复杂的数据结构比如多级分类、动态目录树、每篇文章独立浏览量统计T3 这种极简路线会需要你自己去加代码体验上不一定划算。另外如果你完全不想接触任何命令行操作就想打开网页填个标题点发布那还是传统后台方案更顺手。T3 的定位一直很明确给愿意掌控自己的内容的写作者用不是给“一切帮我代劳”的用户用。2. 从零搭建仓库结构、本地环境与写作流2.1 准备一个仓库T3 的部署方式决定了你首先要有一个 Git 仓库。我建议直接用它的模板仓库来初始化而不是从零手写因为项目里已经包含了一整套内容目录、样式文件和构建配置省去大量起步工作。初始化时章鱼副歌分两步进入 T3 的 GitHub 页面使用模板创建你自己的仓库命名比如my-blog。把仓库克隆到本地git clone gitgithub.com:你的用户名/my-blog.git。之后所有操作都围绕这个本地仓库进行。你需要装的只有 Node.js 和包管理器npm 或 pnpm。Node 版本建议选 LTS 版本避免某些编译依赖在过旧版本上报错。依赖安装我用的是 pnpm原因很简单T3 项目本身依赖较多pnpm 的硬链接机制能省不少磁盘空间安装速度也快。命令行只有一句话pnpm install装完直接pnpm dev本地服务默认跑在localhost:3000。打开浏览器看到默认首页说明环境没问题可以开始往里写内容了。2.2 目录结构与内容组织T3 的内容组织方式很有代表性。项目里有一个专门的content目录所有文章按年份或主题分子目录存放这个划分逻辑是模板自带的你也可以改成自己喜欢的方式。我的目录是这样的content/ ├── posts/ │ ├── 2024/ │ │ ├── 01-初识-t3.md │ │ └── 02-博客部署.md │ └── 2025/ │ └── 01-写作流程复盘.mdx └── pages/ ├── about.md └── uses.mdposts放正式文章pages放固定页面比如“关于我”。T3 会递归扫描整个content目录你不需要主动注册任何路由文件放进去、推上去页面就有了。这个设计很符合直觉——你在文件系统里如何组织文章在站点上就会如何呈现。文件名我习惯用日期-英文短横线标题格式。日期信息在文件名里保留一份后面做归档排序时非常方便。中文长标题放在文件内容里作为 Frontmatter 的title字段这样 URL 保持简洁可靠页面的显示标题又不受影响。2.3 Frontmatter 与写作规范每一篇文章的开头都有一小段 YAML 格式的元信息T3 靠它识别标题、日期、摘要和标签。我常用的字段是这几个--- title: 用 T3 搭建个人博客的完整记录 date: 2025-01-12 summary: 从仓库初始化到部署上线的全过程包含踩坑记录。 tags: [博客, Next.js, 写作] ---有几个字段的作用值得展开说summary是我强烈建议大家写的字段。T3 在列表页和社交媒体卡片里都会用到它。如果留空系统会自动截取正文前几个字符但自动截取往往在语义上不够准确自己想一句摘要表达会更精准别人也更容易判断值不值得点进来。tags用来组织文章。T3 的标签页会把所有标签聚合成一个页面点击某个标签能看到所有打上该标签的文章。标签命名上我吃过亏一开始随手写了大小写不同但含义相同的词比如“Nextjs”和“Next.js”后来标签页里同一个主题被拆成了两堆。后来我统一成小写加连字符的风格比如nextjs、markdown再没出过这个问题。Frontmatter 之外还有一个小设置很容易忽略draft字段。写草稿的时候把它设成trueT3 会自动跳过渲染本地却仍然可以看到预览。我在每次发布前会单独跑一遍文章列表检查确认没有残留的草稿标记。3. 部署上线Vercel 构建、环境变量与域名3.1 Vercel 导入项目的完整流程T3 的部署我直接用的 Vercel这是跟 Next.js 同源的最顺滑方案。把仓库推送到 GitHub 之后登录 Vercel 控制台点击“Add New Project”选择你的博客仓库剩下的交给平台就行。整个流程里有一个关键点容易被新手忽略框架预设。Vercel 会自动识别 Next.js并把构建命令设置为next build。我建议在导入时把框架预设确认一下因为有些仓库会不小心被识别成其他框架。识别错误的话构建大概率会失败而且失败日志对小白来说并不友好。导入页面里不用特意改任何构建参数默认的npm run build或 pnpm 对应的 build就能通过。点击 Deploy 后第一次构建会跑 3 到 5 分钟看网络情况。数秒后你会收到一个默认的.vercel.app域名站点已经可以直接访问了。等这个域名能打开就说明从仓库到线上这条链路已经打通。3.2 环境变量与构建配置很多网友以为 T3 部署完就完事了但实际上有些功能需要环境变量才能启用。最典型的是“文章增量更新”相关的机制需要配置 GitHub Token这样站点构建时才能自动拉取最新的内容提交。环境变量的配置路径是 Vercel 项目设置里的Environment Variables页面。我配置的变量结构大致是名称 值 TOKEN ghp_你的GitHub个人访问令牌这个 Token 在 GitHub 个人设置里生成理论上给repo相关权限就够了。生成之后你可以自己在本地用一行命令测试它是否有权限访问目标仓库curl -H Authorization: token 你的TOKEN https://api.github.com/repos/你的用户名/my-blog返回正常 JSON 说明权限没问题。“能用”和“好用”之间往往就差这一个看似多余的验证步骤省得部署完发现功能异常还得回头查权限。3.3 自定义域名与 HTTPS默认的vercel.app域名适合临时体验正式写博客我建议绑定自己的域名体验和可维护性都会好很多。绑定流程简单说三步在 Vercel 项目的 Domains 里填入你的域名到域名服务商那边按提示添加一条 CNAME 记录指向 Vercel 给的地址通常是cname.vercel-dns.com保存之后等待几分钟Vercel 会自动申请和续期 HTTPS 证书。整个过程不需要自己手动上传证书这是托管平台最大的省心之处。需要注意的是如果你用的是国内域名服务商DNS 解析记录生效可能需要更长时间有时候要半小时以上不要急着一分钟刷新几十次。我当时的做法是先去泡杯茶过几分钟再回来看通常就绿了。4. 写作体验进阶MDX、公式、代码高亮与组件4.1 Markdown 之外的 MDXT3 不只是支持普通 Markdown还支持 MDX。MDX 简单说就是在 Markdown 里可以直接嵌入 React 组件。这让一篇博客文章不光是静态文字还能具备交互能力。举个实际例子如果你写一篇关于某种算法的文章普通 Markdown 只能展示代码块和文字而 MDX 可以内嵌一个可交互的演示组件——比如一个滑块读者拖动就能看到不同参数下的运行效果。这在技术博客里带来的阅读体验提升远比截图和文字描述强。我自己的用法相对保守最常用的是把一些固定的排版模块封装成组件然后在文章里调用。比如“提示框”和“参考资料”这两个组件我用在多数技术文章里。写法类似import Callout from components/callout; Callout typewarning 这段代码依赖 Node 18 以上环境低版本会导致启动失败。 /Callout这样每次要写提示时不用重复排版而且全站风格保持一致。T3 的组件位置放得比较清晰按作者的仓库目录结构放就能被 MDX 解析器找到。4.2 LaTeX 公式与代码高亮技术博客绕不开数学公式。T3 对 LaTeX 的支持开箱即用行内公式用$...$块级公式用$$...$$。我写一些带复杂度推导的文章时不用切任何编辑器直接在 Markdown 文件里写公式最终渲染的效果和学术论文差不太多。举一个最常见的使用场景。在文章中写行内公式梯度下降的更新规则是 $θ : θ - α \cdot \nabla J(θ)$其中 α 是学习率。渲染出来就是一个干净的数学表达式不用去生成公式图片再引用维护起来也方便得多——文本文件里要改公式就是直接改那几个字符。代码高亮同样是搭建完就有的能力。它支持常见的语言标注比如const greeting (name) Hello, ${name};T3 会把代码块渲染成带行号和高亮的样式某些语言的关键字颜色区分很清楚。我特别满意的是它对长代码的换行处理不像有些博客系统那样把横条拉得老长而是过度长代码自动换行移动端阅读体验友好。4.3 摘要、标签与 SEO 细节前面提到 Frontmatter 里的summary字段它在 SEO 层面的价值比我们想象中还大因为它不仅出现在文章列表页还会成为社交分享卡片里的描述文本。我在各地群分享文章链接时别人看到的那段简介就是我写的 summary而不是系统乱抓的正文首句。自从我把每篇摘要用心写之后从第三方平台跳转过来的阅读量有明显变化。T3 对每个标签会自动生成一个页面这个功能对内容沉淀很有益。读者读完一篇文章顺着标签能继续找到同一主题的其他文章停留时间会显著变长。我在部署前原本打算自己写标签聚合页后来发现 T3 已内置了支持省了一大截开发量。SEO 的另一块是小细节站点的元信息比如 title、description、favicon。T3 的配置文件里留好了统一入口不用到每个页面去改。我把自己的站点描述从默认文案改成一句话定位后搜索引擎抓取到的摘要信息就变得准确多了。这件事做在写第一篇文章前后面所有页面的元信息都能自动带上这些基础设置。4.4 为文章设置正确的写作环境本地写作有一个非常容易被忽视的问题Markdown 的换行和空格细节。默认 Markdown 规则里换行不一定等于段落的拆分你需要在行尾加两个空格或者留一个空行段落之间才会正确分开。我在刚开始写作时很不习惯写完总是显示成一个巨大的文本块。后来我统一了做法每个段落之间绝对留一个空行段落内部绝不打两个多余空格。这样不管在什么 Markdown 渲染器里看排版都不会乱。还有个细节是中文引号。我平时写代码习惯了 ASCII 环境写文章时打引号会直接用半角双引号结果在页面里看着非常别扭跟中文内容格格不入。后来我在本地装了一个自动把半角引号转成全角引号的小工具写完后统一跑一遍转换视觉上立刻自然很多。这类“编辑器层面的小设定”对人阅读体验的影响常被写博客的人忽略。5. 踩坑记录我从“能用”到“好用”的排查过程5.1 坑一改了文章线上却看不到更新第一次遇到这个问题是在上线最初几天。我在本地改了文章标题推送到 GitHubVercel 的构建日志里显示部署成功了但打开线上页面看到的还是旧标题刷新多少遍都不变。我一开始以为是缓存问题在浏览器里清空缓存重试没有变化。后来把范围缩小到Vercel 构建成功、线上静态资源也更新了那变数很可能在数据源。排查发现我的仓库确实收到了提交记录但 T3 在构建时拉取内容依赖那个 GitHub Token 的权限配置而我当时根本没有配置这个环境变量导致构建时没有读取到最新的提交而是用本地缓存的数据。找到根因后我做了两件事第一在 Vercel 里配置好具有正确权限的 Token第二重新触发一次部署。这次打开页面新标题正常显示。从此之后我每次提交后会在 Vercel 构建日志里确认它有没有执行“内容拉取”这一步有就放心了没有再发生过同类问题。5.2 坑二图片路径本地与线上不一致写文章时插入图片用的是相对路径本地预览正常部署到线上后却发现图片裂了。这个问题很典型原因在于本地开发时文件的物理路径与线上构建后的静态资源路径不完全相同。我的图片是放在文章同级的目录里的文章引用的方式是./images/流程图.png。本地预览时Markdown 解析器能找到相对路径但部署阶段T3 会把 Markdown 内容映射到站点的 URL 体系里相对路径就变成了相对于当前路由。如果文章路由是/posts/2024/01-初识-t3那么./images/流程图.png会被解析成/posts/2024/01-初识-t3/images/流程图.png这显然不对。后来我改用公共资源目录方案把图片统一放在项目的public目录下的images/posts/xxx/文件夹里文章里直接写绝对路径/images/posts/xxx/流程图.png。这样无论本地还是线上路径都指向同一个位置不再依赖于文章的物理位置。5.3 坑三代码块里的特殊符号被吞掉某次写一篇讲命令行工具的教程代码块里有一行$echo $HOME类似的内容渲染出来总是少字符。开始我以为是自己手误关掉自动格式化后才发现问题出在 Markdown 解析时的字符转义。在 Markdown 的某些解析规则里字符与特殊格式可以共存也会冲突。尤其是用到*、_、反引号这些与 Markdown 语法冲突的字符如果不加注意渲染结果就会异常。我的解决方法是代码块的语言标注一定写准确不写语言或者标错语言解析器会启用不同的高亮处理逻辑而有些高亮逻辑对特殊字符转义是双重的。现在我在代码块里只使用明确标注语言的方式遇到冲突字符时优先用 HTML 实体编码而不是硬写原文。这个方法在大多数渲染场景下都稳。5.4 一个小坑修改 Frontmatter 导致文章渲染失败有次我把摘要写得太长超过了从某个字符开始的部分页面直接报错。排查下来是 YAML 的解析问题——摘要里包含了一个冒号而我没有用引号把它包起来YAML 解析器把冒号后面的内容当成了嵌套结构。从那以后Frontmatter 里的所有字段值我统一用引号包裹特别是标题和摘要这类容易出现带标点内容的地方。用引号包裹之后冒号、感叹号、特殊符号都不会再影响解析。这个习惯后来帮我避免了很多麻烦包括发出去的定时任务和脚本在读取 Frontmatter 时也都能正确解析。5.5 盘点一下“本地正常、线上异常”这类问题这类问题排查时我总结了一条顺口溜先看构建日志再看环境变量最后怀疑路径和缓存。顺序很重要构建日志确认线上代码确实更新到了最新版本。环境变量确认与 GitHub 交互的凭证、自定义变量都配好了。路径确认所有静态资源的引用方式在构建产物里依然有效。缓存确认 CDN 和浏览器缓存没有把旧版本锁住。按照这个顺序排查绝大多数“本地正常线上异常”的问题都能在十分钟内定位。6. 写作习惯的变化与值得做的扩展6.1 写作习惯的变化用了 T3 之后我的写作习惯发生了两个明显变化。一个是从“后台打字”变成了“编辑器写作”。过去用后台时我总想开着网页直接写写到一半又忍不住去看排版效果。现在我在本地编辑器里写眼睛盯住文字本身排版效果反而没那么在意了。这个变化让我写完整篇初稿再一次性发布的频率大大提高。另一个变化是“提交频率”显著变高。以前写完文章是一次性保存现在写完一个小节就 commit 一次把文档写成一种“版本化日志”。好处很明显写坏了可以回退到任何一个历史版本写不下去时重新读历史 commit 能快速找到思路。我强烈建议写长篇技术博客的朋友养成这个习惯成本极低收益却非常实在。6.2 值得做的扩展方向T3 默认是够用的但如果你愿意稍微折腾有几个方向很值得做。第一个是评论系统。T3 本身不带评论区我集成了一个基于 GitHub Issue 的评论方案读者评论时本质上是在文章对应的 Issue 里留言。这个方案有一个我不太喜欢的点是不是每个读者都有 GitHub 账号会挡掉一部分想评论的人。但它胜在零服务端成本、内容可控而且跟“内容存在 GitHub 上”的整体思路完全一致。第二个方向是接入第三方的浏览量统计。T3 是纯前端项目加统计脚本非常方便。我在全局布局里注入了一段统计代码只统计页面级事件。这里提醒一句接入统计时尽量绕开与用户身份强绑定的方案毕竟博客是公开内容保留访客的基本隐私对读者的体验更友好。第三个方向是内容形态的扩展。T3 既然支持 MDX我后来把一些“半成品”的交互演示做成了文章内的内嵌组件比如一些简单算法的可视化。读者看文章的时候可以直接拖动参数观察结果变化这种内容的去留往往决定一篇技术博客是否被收藏。目前我通常只给重点文章加这个待遇因为开发成本还是在的。6.3 我现在的日常发布流程最后分享我的标准流程非常简单一眼看完在content/posts/下新建文件写好 Frontmatter。写作过程中写一段就git commit一次。全文写完检查一遍 summary 和 tag确认无草稿标记。git push等 Vercel 构建完成后确认页面更新。整套流程从写完到发布人类操作大约一分钟。这份“无摩擦”的体验是 T3 给我最强烈的感受。它让我愿意多写、常更而不再把发博客当成一项要跨过很多步骤的麻烦事。我也说说个人体会博客这件事工具不必多够纯粹就好。T3 通过把复杂的发布流程简化成“提交文件”帮我腾出了原本浪费在后台和插件上的精力全部放回文字本身。如果你的目标也是认真写点东西这套方案值得你花半天时间折腾一下。
