开头：为什么你的教程「看的人多，照着做的人少」？

写技术教程最挫败的瞬间：文章收藏过千，评论区却全是「第 3 步就失败了」。不是读者笨，是文章结构没有服务「照着做」——大段原理铺垫、步骤之间没有预期输出、报错没有排查指引，读者走到一半就迷路了。

我研究了三家公认「教程质量天花板」的站点——web.dev（Google 官方）、DigitalOcean（云厂商社区）、freeCodeCamp（全球最大免费编程社区），拆解它们的代表性教程（CSS Box Model / PostgreSQL 安装 / ToC 写作规范），提炼出可复制的结构件与流程，并落地成本站 scaffolds/tutorial.md 脚手架。

目标声明 + 前置条件

本文带你完成：理解六种结构件的作用与写法、学会按「钩子 → 目标 → Step → 检查点 → FAQ → 延伸」编排一篇教程，并直接使用本站的教程脚手架开写。

前置条件：

• 有想写的技术主题（哪怕只有一个函数/一次踩坑）
• 本站 scaffolds/tutorial.md 脚手架已入库（hexo new tutorial "标题" 使用）

你将学会：

1. 三家教程站的结构共性
2. 六大结构件的写作要点
3. 从大纲到发布的编写流程

Step 1：理解三种教程「形态」

目的：先给文章定形。做完这步知道自己的主题该用哪种形态。

判断方法：你的读者是要「理解」还是要「做完」？理解→课程型，做完→步骤型，两者都要→实战型。

Step 2：开头写钩子（1~3 行）

目的：制造「预期与现实的矛盾」，让读者产生「为什么？」的好奇。做完这步读者决定要不要读。

三种钩子模板：

写不好钩子 = 文章没人读。这是唯一一个「值得花 10 分钟写 3 行」的部分。

Step 3：写目标声明 + 前置条件

目的：读者自评「该不该读、能不能跟上」。做完这步过滤无效流量。

结构：

1
2
3
4
5
6
7
8

本文带你完成：XXXX（一个明确成果）。
**前置条件：**
- [ ] 已安装 X（未安装参考 [教程](链接)）
- [ ] 已配置 Y
- [ ] 预计耗时 30 分钟
**你将学会：**
1. X
2. Y

Step 4：Step 用「操作 + 预期输出 + 排查」三明治

目的：每一步都可验证、可复现、可自救。做完这步文章的核心骨架成型。

每步格式：

1
2
3
4
5
6
7
8
9

## Step N：标题（动词开头）

> 目的：做这一步能看到什么效果（可验证的预期）。

**操作：**（命令/代码，可直接复制）

**预期输出：**（粘贴你真实跑出来的输出，读者照此核对）

> ⚠️ 报错排查：如果出现 X 错误，通常是 A/B 导致，检查 C。

要点：

• 预期输出必须写：DigitalOcean 每步都贴真实输出，读者对得上才敢继续
• 命令块前加 sudo/环境提示：读者环境 ≠ 你的环境
• 报错排查放当步（不是文末）：卡住的人不会读到文末

Step 5：加检查点 + FAQ

目的：给读者一个「完成自测清单」和「失败对照表」。做完这步文章闭环。

1
2
3
4
5
6
7
8

## 检查点：验证整体效果
- [ ] 页面出现 X 效果
- [ ] 控制台无报错
（全部勾选通过 = 教程完成）

## 常见问题（FAQ）
| 问题 | 原因 | 解决 |
|------|------|------|

web.dev 每节末尾的「Check your understanding」就是这个思路——读者自测，作者免答疑。

Step 6：总结 + 延伸阅读

目的：回顾核心要点 + 引流系列下一篇。做完这步文章形成「系列闭环」。

1
2
3
4
5
6

## 总结
本文带你完成了 X。核心要点：1. ... 2. ...
**延伸阅读：**
- [上一篇：《XXX》](链接)
- [下一篇：《XXX》](链接)
- [官方文档](链接)

系列文章之间必须互链（freeCodeCamp 规范里 ToC + Conclusion + 下一篇引导是写作模板的一部分）。

编写流程（从 0 到发布）

1
2
3
4
5
6

① 定形态：课程型 / 步骤型 / 实战型
② 写钩子：矛盾代码 / 痛点 / 反直觉结论（3 行）
③ 列大纲：目标 → 前置 → Step 骨架 → 检查点 → FAQ → 总结
④ 按 Step 填内容：操作 → 真实预期输出 → 排查
⑤ 自查：每步预期输出是否可验证？无 404 链接？（本仓库有 CI 死链检查兜底）
⑥ 发布：hexo new tutorial "标题" → 填写 → push

检查点：验证整体效果

用下面清单检查你写出的文章。

• 开头 3 行内有钩子（矛盾/痛点/反直觉）
• 目标 + 前置条件 + 你将学会 三件套齐全
• 每个 Step 都有「预期输出」
• 有检查点勾选清单
• FAQ 表覆盖至少 3 个高频报错
• 延伸阅读互链了系列上下篇

常见问题（FAQ）

总结

教程不是「知识搬运」，是「带读者走完一条路」。核心要点：

1. 结构服务目标：读者要「做完」→ Step 三明治；要「理解」→ 概念 + 测验
2. 预期输出是灵魂：没有它，读者无法确认自己走对了
3. 钩子决定流量：3 行写不好，后面全白写
4. 工具化落地：本站 scaffolds/tutorial.md 已内置全部结构件，hexo new tutorial 即用

延伸阅读：

• 本站教程脚手架 scaffolds/tutorial.md
• web.dev Learn CSS
• DigitalOcean Community Tutorials
• freeCodeCamp 写作规范（RSS 摘录）