> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# cpx 2.0 — Composer Package Executor 全面重写
> 介绍 laravel/cpx。这是一款像 npx 一样、无需安装即可执行 Composer 包的工具。在 v2.0 中被重写为自包含 PHAR，并加入了本地二进制优先执行、Gist 执行、别名功能等。
本文基于 [laravel/cpx](https://github.com/laravel/cpx) 的 README.md 与 UPGRADE.md。内容对应 v2.0.0（发布于 2026 年 7 月 24 日）。
## 什么是 cpx
[cpx](https://github.com/laravel/cpx) 是一款可以在不安装的情况下执行 Composer 包所包含命令的工具。可以将其理解为 npm 中 `npx` 的 Composer 版本。
```bash theme={null}
composer global require cpx/cpx
cpx friendsofphp/php-cs-fixer fix ./src
```
内部会将包安装到隔离的目录中执行，因此不会与项目级或全局的 Composer 依赖发生冲突。第二次及以后的执行会复用同一份已安装的包，因此速度较快。
## 为什么需要它
通过 `composer global require` 单独安装工具的方式存在以下问题：
* 全局依赖之间可能相互冲突（尤其是使用 `nikic/php-parser` 或 `symfony/console` 等公共依赖的工具容易出现）
* 希望不同项目使用同一工具的不同版本
* 长期运行时容易忘记更新全局包
* 不希望为仅用一次的工具进行全局安装
cpx 自身是作为 PHAR 自包含的，运行时不依赖 Composer，因此即便全局安装也不会成为冲突源。
## v2.0 的全面重写
cpx 在 v2.0 中被全面重写，并作为**自包含 PHAR**分发。基本用法（`cpx [arguments]`）与 `~/.cpx` 缓存目录都保持不变。1.x 已冻结开发，包括 bug 修复和安全修复在内今后不会再有版本发布。
升级只需重新执行全局安装。
```bash theme={null}
composer global require cpx/cpx:^2.0
```
v2.0 需要 PHP 8.3 或更高版本。
## v2.0 的新功能
### 本地二进制优先执行
与 npx 类似，如果项目中已经安装了对应的二进制，则会优先执行它，而不是安装隔离副本。cpx 会从当前目录向上查找最近的 Composer 项目，并执行 `vendor/bin`（默认的 `bin-dir`）中匹配的二进制。
```bash theme={null}
cpx pint # 若存在 vendor/bin/pint 则执行它
cpx phpunit --filter=Foo # 若存在 vendor/bin/phpunit 则执行它
cpx laravel/pint:^2.0 # 仅当已安装版本满足约束时才使用本地
```
若要强制使用隔离副本，使用 `--skip-local`。
```bash theme={null}
cpx --skip-local laravel/pint --version
```
### 直接执行本地包目录
可以直接指定开发中的 Composer 包目录，执行其二进制。
```bash theme={null}
cpx /absolute/path/to/package --version
cpx ../path/to/package --version
```
目标目录必须包含有效的 `composer.json`，且依赖需事先安装到 `vendor/autoload.php`。此时 cpx 不会执行 Composer，也不会复制或缓存包。
### cpx exec 与 cpx tinker
提供了多种快速执行 PHP 代码的方式。
| 命令 | 说明 |
| --------------------- | --------------------- |
| `cpx exec ` | 执行 PHP 文件（执行文件仅支持此方式） |
| `cpx exec -r ` | 直接执行 PHP 代码 |
| `cpx exec ` | 下载 GitHub Gist 后执行 |
| `cpx tinker` | 打开交互式 REPL |
在 Laravel 项目内，`cpx exec` 会完整启动应用程序，包括 config、facade、`.env`（`$app` 可用），`cpx tinker` 会执行项目自身的 `php artisan tinker`（若已安装 `laravel/tinker`）。在其他位置则会启动 PsySH shell。
在脚本中可通过 `cpx_require('vendor/package')`（1.x 中的 `composer_require()` 已改名）现场加载包。
### 别名功能
可以定义自己的快捷方式，避免记忆冗长的包名。
```bash theme={null}
cpx alias laravel/pint pint
cpx aliases # 列出已定义的别名
cpx unalias pint # 删除别名
```
1.x 中内置的针对热门包的默认别名列表已被废除，如有需要请自行定义。
### 非交互模式与 JSON 输出
cpx 会通过 [laravel/agent-detector](https://github.com/laravel/agent-detector) 检测 AI 智能体，并从标准输入重定向、`--no-interaction`/`-n` 标志自动检测非交互环境。在非交互模式下，`installed`、`aliases`、`alias`、`unalias`、`clean`、`update` 等 cpx 自身的管理命令会返回一行 JSON 而非格式化文本。即便是交互式终端，也可以通过 `--json` 获得相同的输出。
## 从 v1.x 的主要变化（命令）
| 1.x | 2.x |
| --------------------------------------- | ---------------------------------------------- |
| `cpx list`（已安装列表） | 改为 `cpx installed`（`list` 用于显示命令列表） |
| 内置别名列表 | 已废除。使用 `cpx alias` 自行定义 |
| `cpx check` / `cpx format` / `cpx test` | 已废除。直接执行 `cpx pint`、`cpx phpstan`、`cpx pest` 等 |
| `cpx version` / `-v` | 已废除。使用 `cpx --version` |
| `cpx script.php`（直接执行文件） | 已废除。需使用 `cpx exec script.php` |
| `composer_require()` | 改名为 `cpx_require()` |
## 相关页面
`~/.cpx` 目录的缓存和旧版本包会自动迁移到新格式，但带版本约束执行的包由于以新目录名管理，因此仅首次会重新安装。不再需要的 1.x 时代的副本可以通过 `cpx clean` 删除。
源代码和最新的 README 请见此处。
从 1.x 到 2.x 的详细迁移步骤。
## Related topics
- [Laravel 包开发](/zh-CN/advanced/package-development.md)
- [Eloquent API 资源](/zh-CN/eloquent-resources.md)
- [密码重置](/zh-CN/passwords.md)
- [Laravel Scout](/zh-CN/scout.md)
- [Eloquent 序列化](/zh-CN/eloquent-serialization.md)