Composer如何开发命令行CLI工具包_Composer开发CLI工具包指南-composer-PHP中文网

composer通过bin字段将脚本链接至vendor/bin/或~/.composer/vendor/bin/，需设执行权限、shebang及显式引入autoload.php；path配置、链接有效性与跨环境验证是关键。

composer如何开发命令行cli工具包_composer开发cli工具包指南

Composer 本身不提供 CLI 工具开发框架，但它是分发和加载 PHP CLI 工具包的事实标准 —— 关键在于正确声明 bin、配置 autoload，并确保入口脚本可执行。

如何让 Composer 安装后自动注册命令到系统 PATH

核心是 composer.json 中的 bin 字段。它声明一个或多个可执行脚本路径（相对于项目根目录），Composer 在全局安装（composer global require）或本地安装后，会将这些路径软链接到 vendor/bin/；若用 composer global，还会链接到 ~/.composer/vendor/bin/（需确保该路径在系统 $PATH 中）。

实操建议：

bin 数组里填的是脚本文件路径，不是类名或函数名，例如："bin": ["bin/mytool"]
脚本文件（如 bin/mytool）必须有 Unix 执行权限（chmod +x bin/mytool），Windows 用户用 Git Bash 或 WSL 开发时同样需要
脚本第一行必须是 shebang，如 #!/usr/bin/env php，否则 shell 执行时报 Permission denied 或直接忽略
不要在 bin/mytool 里写大量逻辑，只做最小引导：加载 autoloader，实例化主命令类，调用 run()

为什么 CLI 入口脚本不能直接 new 类而要先加载 autoload

因为 Composer 的自动加载机制（由 vendor/autoload.php 驱动）不会自动生效 —— CLI 脚本是独立进程入口，PHP 不会像 Web 请求那样隐式包含 autoloader。

常见错误现象：运行 mytool 报 Fatal error: Class 'MyTool\Application' not found，即使类已按 PSR-4 正确声明。

实操建议：

入口脚本开头必须显式引入：require __DIR__.'/../vendor/autoload.php';
路径要写对：__DIR__ 是 bin/ 目录，所以 ../vendor/autoload.php 才能命中（本地开发）；全局安装时，__DIR__ 指向 ~/.composer/vendor/xxx/yyy/bin/，相对路径依然成立
避免用 require_once 'vendor/autoload.php'（少个 ../）或硬编码绝对路径（破坏可移植性）

如何支持全局安装 + 命令补全（bash/zsh）

Composer 只管链接，补全是 Shell 层的事。工具自身需提供补全脚本，并提示用户手动启用。

Workflow Decomposer

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

下载

使用场景：用户希望输入 mytool [tab][tab] 列出子命令，或 mytool run --[tab] 补全选项。

实操建议：

在项目中提供 contrib/mytool-completion.bash（或 .zsh），内容调用 Symfony Console 的 completion 命令（如果基于 Console 构建）
文档明确写出启用方式，例如：source /path/to/mytool/contrib/mytool-completion.bash，并建议加到 ~/.bashrc
不依赖 Composer 自动注入补全 —— 它没这个能力；也不要试图在 bin/mytool 里动态生成或加载补全逻辑，那属于运行时开销且不可靠
验证方式：新开终端，执行 type _mytool，有输出说明补全已加载

为什么 vendor/bin 下的命令有时“找不到”，有时又正常

根本原因只有两个：PATH 未包含 vendor/bin，或当前执行的是旧链接（如切换分支后未重装依赖）。

性能与兼容性影响：Composer 7+ 对 bin 链接做了缓存优化，但 Windows（CMD/PowerShell）下仍可能因符号链接权限失败而回退为复制，导致更新滞后。

实操建议：

检查当前 PATH：echo $PATH | grep vendor（Linux/macOS）或 echo %PATH%（Windows CMD）
确认链接真实存在：ls -l vendor/bin/mytool，应指向 ../packages/name/bin/mytool，而非死链接
遇到异常优先执行：composer install --no-cache（清除 bin 缓存）或 composer dump-autoload（仅刷新自动加载）
CI/CD 环境中避免用 vendor/bin/mytool，改用 php bin/mytool 绕过链接问题（更稳定）

CLI 工具包最难缠的不是功能实现，而是跨环境的一致性：不同用户的 composer global 路径、Shell 类型、权限策略、甚至 Git 配置（core.autocrlf）都可能让 bin 脚本静默失效。每次发布前，在干净 Docker 容器里跑一遍 composer global require + 手动执行，比写十个单元测试更能暴露问题。