技术写作：如何写出有价值的技术文章

从 2022 年开始写技术博客，到现在三年了。从没人看到有几万阅读，分享一些心得。

为什么要写

收益	说明
知识沉淀	写出来才算真正理解
个人品牌	面试时的加分项
反馈成长	读者的评论和纠错
职业机会	猎头主动联系

什么样的文章有价值

有价值的类型

1. 踩坑实录：真实的失败经历和解决方案
2. 深度解析：不只是 API 文档的翻译
3. 实战经验：项目中的真实问题
4. 对比评测：帮读者做技术选型

没价值的类型

1. 翻译官方文档
2. 复制粘贴教程
3. 没有观点的”总结”
4. 八股文式的面试题

写作框架

问题驱动

背景：遇到了什么问题
分析：为什么会这样
方案：怎么解决的
总结：学到了什么

示例：

我们有个接口响应突然变慢，从 50ms 飙到 2s。排查发现是数据库索引失效，原因是…最终通过…解决。教训是…

对比驱动

方案 A：优点、缺点
方案 B：优点、缺点
选择：为什么选这个

标题很重要

不好的标题

• 《深入理解 React Hooks》
• 《TypeScript 完全指南》
• 《Vue 3 教程》

太大、太空，读者不知道能学到什么。

好的标题

• 《React useEffect 的三个常见陷阱》
• 《TypeScript 泛型：一个表单组件的实战案例》
• 《Vue 3 组合式 API：从选项式迁移踩过的坑》

具体、有场景、有痛点。

内容组织

开头要抓人

不要写：

React 是 Facebook 开发的 JavaScript 框架，2013 年发布…

没人关心这个。直接说问题：

上周重构代码，useEffect 的依赖数组搞得我头大。研究了两天，终于搞明白了…

代码要有上下文

不好的代码示例：

// 一个孤立的函数
function handleClick() {
  setState(!state);
}

好的代码示例：

// 问题：点击按钮后状态没更新
// 原因：直接取反，丢失了闭包中的旧值
function ToggleButton() {
  const [isOn, setIsOn] = useState(false);

  const handleClick = () => {
    setIsOn(!isOn);  // 这里可能拿到旧的 isOn
  };

  // 解决：使用函数式更新
  const handleClickFixed = () => {
    setIsOn(prev => !prev);  // 保证拿到最新值
  };
}

表格是好工具

复杂的概念用表格对比：

方案	性能	复杂度	推荐场景
A	高	低	小项目
B	中	中	中项目
C	低	高	大项目

常见问题

不知道写什么

从记录开始：

1. 今天解决了什么 Bug
2. 学到了什么新东西
3. 踩了什么坑

不用追求”大作”，小文章也有价值。

怕写得不好

没人一开始就写得好。先发出来，接受反馈，慢慢改进。

我第一篇文章现在看简直惨不忍睹，但这不重要，重要的是开始了。

没时间写

利用碎片时间：

1. 写大纲（10 分钟）
2. 写主体（30 分钟）
3. 修改润色（20 分钟）

一篇文章不用一次写完，可以分几天。

发布平台

平台	优点	缺点
个人博客	完全可控	流量少
掘金	流量大、社区活跃	水文多
知乎	SEO 好	战争多
微信公众号	私域流量	排版麻烦

建议：主阵地一个，其他同步发。

一些技巧

配图

一图胜千言。复杂流程用图表示：

• 流程图：Mermaid、Draw.io
• 架构图：Excalidraw
• 截图：Snipaste

格式

• 段落不要太长
• 多用小标题
• 重点加粗
• 代码块标注语言

校对

发布前检查：

1. 错别字
2. 代码能否运行
3. 链接是否有效
4. 逻辑是否通顺

总结

技术写作不是为了炫技，是分享和沉淀。

关键点：

1. 写真实经历
2. 有具体场景
3. 提供解决方案
4. 保持输出

开始写，比写得好更重要。