readme.md必须包含五大不可缺区块：项目概述（500字内直述功能）、运行环境（PHP/MySQL等具体版本）、开发部署步骤（含git clone至artisan migrate全流程）、扩展包说明（表格列明包名及用途）、API与自定义命令/队列文档（含全限定名及触发逻辑）。
readme.md 是每个 Laravel 项目必须存在的入口文档，它不是可选附件，而是新成员上手、CI/CD 流程触发、线上部署核查的第一依据。没它，等于没项目。
readme.md 必须包含哪些区块
不是“建议写”，而是缺一不可，否则团队协作会卡在第一步：
- 「项目概述」——500 字内说清这是什么系统、面向谁、核心功能三句话讲完；避免出现“本系统旨在……”这类空话，直接写“用户注册登录、订单管理、对接微信支付”
- 「运行环境」——明确写出 PHP 版本（如
PHP >=8.1）、MySQL 版本（如MySQL 8.0+）、Redis 是否必需、Node.js 是否用于构建前端资源 - 「开发环境部署/安装」——从
git clone开始，到php artisan migrate成功为止的每一步命令，含.env必填项说明（比如APP_KEY必须执行php artisan key:generate） - 「扩展包说明」——用表格列明所有
composer require安装的非官方包，例如knuckleswtf/scribe用于 API 文档生成，spatie/laravel-permission用于 RBAC 权限控制，不写用途等于没写
API 文档不能靠手写，必须自动化生成
手动维护 Markdown 或 Postman Collection 会在两周内失效。Laravel 生态有两个主流选择，选错版本或注释格式会导致 php artisan scribe:generate 或 php artisan l5-swagger:generate 直接静默失败：
-
Scribe更轻量，适合内部系统：注释必须用@queryParam、@response这类 Scribe 自有语法，且控制器方法上方不能有空行隔开注释与public function -
l5-swagger强制要求 OpenAPI 3.0 注释：必须以@OA\Get开头，@OA\Parameter必须带in="path"或in="query"，漏掉就不出现在 URL 模板里；Laravel 10.x 必须用darkaonline/l5-swagger:^9.0，用 ^8.0 会因config_path()调用方式变更报错 - 两者都需配置扫描路径：默认只扫
app/Http/Controllers，若 API 控制器在app/Http/Controllers/Api/V1，必须手动改config/scribe.php的routes → include或config/l5-swagger.php的paths → apis
自定义 Artisan 命令和队列必须登记在文档中
没人会翻代码找 php artisan import:users 的参数含义，也没人记得 SendWelcomeEmail 队列是否要设置 --delay=300。这些信息必须结构化呈现：
- 「自定义 Artisan 命令列表」表格至少含三列：
命令名（如cache:clear-all）、用途（如 “清空 Redis 中所有业务缓存键，不含 Laravel 默认缓存前缀”）、调用场景（如 “上线后手动执行，不纳入 deploy 脚本”） - 「队列列表」表格同样三列：
队列名（如App\Jobs\ProcessPayment）、触发时机（如 “用户提交订单后由 OrderController@store 分发”）、注意事项（如 “必须配置QUEUE_CONNECTION=redis，不支持 database 驱动”） - 所有命令和队列类名必须用
App\Jobs\...或App\Console\Commands\...全限定名，避免 IDE 点击跳转失效
文档不是写完就扔，而是要进 CI/CD 和日常习惯
最常被忽略的一点：文档更新滞后于代码，本质是缺乏验证机制。真实项目里，这三点必须落地：
-
php artisan scribe:generate或php artisan l5-swagger:generate必须加入 CI 流程，失败则阻断合并；否则 PR 合入后文档就已过期 -
readme.md中的部署步骤必须能被新同事在 15 分钟内走通，如果某步需要“联系运维开权限”，那这步就得写成“联系 @ops-team 提供 DB_HOST 和 DB_PORT”并标注 Slack 频道 - 每次新增扩展包、自定义命令、队列任务，第一件事不是写代码，而是先更新对应表格——文档和代码是同一提交的两个文件，不是“后续补上”
