写了几年笔记,回头看大部分都没再打开过。真正有用的笔记有个共同点:它是为了解决一个具体问题而写的,不是为记录而记录。
三种值得写的笔记
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 版本与服务器配置调整;涉及生产环境的变更,建议先备份并在测试环境验证。