技术博客写作规范

本文档为有来开源项目（vue3-element-admin、youlai-boot 等）配套文档，统一技术博客的写作风格。

核心原则

借鉴 技术博客写作最佳实践：

• 一篇文章只讲一件事：试图覆盖"Docker 网络、卷、多阶段构建"的文章什么都教不好。一篇只讲"容器间为什么不能通信，怎么用 bridge 网络修复"的文章才有深度。动笔前完成这句话："读完本文，读者能 _____"
• 先讲问题，再讲方案：不要一上来就给解决方案。先描述具体问题（"查询要 12 秒，用户在等"），让读者判断是否与自己相关
• 先讲为什么，再讲怎么做：给命令的同时解释为什么这样做。测试：读完之后，读者能否在略微不同的场景中做出合理决策？不能就说明只教了"怎么做"没教"为什么"
• 代码必须可运行：完整 import、无占位符、真实数据、展示输出。读者复制跑不通，信任就断了
• 为带着问题的读者写：技术读者是来解决问题的，不是来读教材的。把答案前置，再给解释

开头结构编排规则

一条铁律

标题（#）与 ## 前言 之间禁止放任何游离内容。 摘要、指标表、截图都是前言的组成部分，必须收进 ## 前言 内部，由引导语引出。