Composer如何编写包的README文档_Composer包README文档编写攻略-composer-PHP中文网

readme 必须包含安装、使用、配置、贡献四大区块，以用户真实搜索路径为准；首行需直击痛点，示例可复制粘贴，仅暴露稳定接口，显式声明版本兼容性与废弃提示。

composer如何编写包的readme文档_composer包readme文档编写攻略

Composer 包的 README 不是装饰品，它直接决定别人愿不愿意装你的包、能不能快速用起来、出错时敢不敢提 issue。写得模糊或缺失关键信息，composer require 成功后，用户卡在第一步——连怎么实例化类都找不到。

必须包含的 4 个区块：安装、使用、配置、贡献

这不是格式建议，而是用户真实搜索路径：how to install my-package → my-package example usage → my-package config options → my-package pull request。缺一个，就会触发大量重复咨询。

安装区块只写一行命令：composer require vendor/my-package；如果需要额外步骤（如发布配置），明确写出 php artisan vendor:publish --tag=my-package-config（Laravel 场景）或 cp vendor/vendor/my-package/config.php ./config/（原生 PHP）
使用区块以可复制粘贴的最小完整示例开头，比如调用 MyPackage\Client::make() 而不是 “初始化客户端” 这种描述
配置区块列出所有环境变量或配置文件键名，如 MY_PACKAGE_API_KEY、timeout，并标注是否必填、默认值、类型（string/int/bool）
贡献区块写清本地开发流程：如何安装依赖（composer install）、运行测试（vendor/bin/phpunit）、代码规范检查（vendor/bin/phpcs）

别把 README 当成 API 文档来写

用户第一次接触你的包，不是来学设计模式的。过度展开类继承关系、事件生命周期、内部 trait 用法，只会让真正想发请求的人翻到第三屏还找不到 $client->send() 的调用方式。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

只暴露稳定、公开、有文档保障的接口：如 MyPackage\Http\Client、MyPackage\Transformer::fromArray()
私有方法、内部 helper 类、未打 @api 标签的函数，一律不写进 README

如有复杂流程（如 OAuth 授权链），用带注释的代码块代替文字描述：

// 1. 获取授权 URL
$url = $auth->getAuthUrl();
// 2. 用户跳转后回调，传 code
$token = $auth->exchangeCodeForToken($_GET['code']);
// 3. 使用 token 初始化 client
$client = new Client($token);

版本兼容性必须显式声明，不能靠猜测

README 里写 “支持 PHP 7.4+” 是无效信息。用户真正需要的是：“PHP 8.2 下 MyPackage\Serializer::jsonEncode() 返回 string|false，而 PHP 8.0 返回 string”，或者 “Laravel 10 需要 v3.2.0+，因移除了 Illuminate\Support\Facades\Response”。

在顶部加一行兼容性横幅：Supports PHP ^8.0|^8.1|^8.2, Laravel ^9.0|^10.0, Symfony ^6.0

若某功能仅限特定版本，直接绑定到示例旁：

// PHP 8.1+ only
$result = match ($status) {
    200 => 'ok',
    default => throw new InvalidStatusException($status),
};

废弃（deprecated）功能要在 README 中明确标出，并给出替代方案，例如：MyPackage\LegacyConnector is deprecated since v2.5.0 — use MyPackage\Http\Client instead.

最难写的其实是第一行——不是 “A package for doing X”，而是 “Use MyPackage\BatchProcessor to run 10k rows without memory overflow”。用户扫一眼就要知道：这东西能不能立刻解决他正在 debug 的那个问题。其他都是为这句话服务的细节。