写了几年笔记,回头看大部分都没再打开过。真正有用的笔记有个共同点:它是为了解决一个具体问题而写的,不是为记录而记录。

三种值得写的笔记

1. 排错记录

格式固定:现象 → 排查过程 → 根因 → 修复 → 如何避免。这类笔记复用率最高,因为同样的错一定会再犯。

## 现象
上传大文件返回 500,日志无 PHP 报错

## 排查
1. 改小文件可上传 → 排除权限问题
2. 查看 nginx error.log → client intended to send too large body
3. 确认 php.ini 已改 → 但 nginx client_max_body_size 仍是默认 1m

## 根因
Nginx 层限制未放开,请求根本没到 PHP

## 修复
client_max_body_size 24m; 重载 nginx

## 避免
上传相关配置列成清单:php 三项 + nginx 一项 + 目录权限

2. 原理拆解

用自己的话解释一个机制,比如”PHP 的 Session 是怎么工作的”。写不清楚,说明还没真懂。这类笔记的价值在于逼自己把模糊的理解说清楚。

3. 决策记录

为什么选这个方案、放弃了什么、当时的约束是什么。半年后你会忘记理由,而理由往往比结论更重要。

不值得写的

  • 整段复制官方文档(需要时直接查更快);
  • 没有上下文的代码片段(三个月后看不懂为什么这么写);
  • 纯目录式的”XX 知识点汇总”(信息密度低,检索不到)。

一个可执行的习惯

遇到问题解决后,花五分钟写三行:什么问题、怎么解决的、下次怎么更快。不用追求完整,能让自己三个月后看懂就行。坚持一年,你会发现自己的排错速度明显变快——不是因为变聪明了,而是因为不再重复踩同一个坑。

关于公开写作

把笔记整理成文章发出来,最大的受益者是自己:写给别人看会逼你把逻辑理顺。不必等到”写得够好”才开始,技术文章的价值在于准确和具体,不在文采。

本文为 PHP 学习与排错的经验整理。示例代码以通用环境为前提,请结合自身 PHP 版本与服务器配置调整;涉及生产环境的变更,建议先备份并在测试环境验证。