> ## 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 執行、別名等功能。

<Info>
  本文根據 [laravel/cpx](https://github.com/laravel/cpx) 的 README.md 與 UPGRADE.md 整理。內容為 v2.0.0（2026 年 7 月 24 日發佈）當時的資訊。
</Info>

## 什麼是 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 <package-name> <command> [arguments]`）與 `~/.cpx` 快取目錄維持不變。1.x 已停止開發，包含 bug fix 與安全性修正在內皆無後續發佈。

升級只需重新做一次全域安裝即可。

```bash theme={null}
composer global require cpx/cpx:^2.0
```

v2.0 需要 PHP 8.3 以上。

## v2.0 的新功能

### 本地執行檔優先執行

與 npx 相同，若專案中已有安裝執行檔，會優先執行它，而不裝隔離副本。從目前目錄向上尋找最近的 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 <file.php>` | 執行 PHP 檔案（檔案執行僅此方式） |
| `cpx exec -r <code>`  | 直接執行 PHP 程式碼        |
| `cpx exec <gist url>` | 下載並執行 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()` 更名）於當下 autoload 套件。

### 別名功能

可自訂快捷方式，就不必記住冗長的套件名稱。

```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 Agent、標準輸入是否被重新導向、以及 `--no-interaction` / `-n` flag，自動判斷是否為非互動環境。在非互動模式下，`installed`、`aliases`、`alias`、`unalias`、`clean`、`update` 等 cpx 管理指令會回傳單行 JSON 而非格式化文字。互動終端也可以加上 `--json` 得到相同輸出。

## 由 1.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` 移除。

<Card title="laravel/cpx 儲存庫" icon="github" href="https://github.com/laravel/cpx">
  原始碼與最新 README 請見此處。
</Card>

<Card title="cpx 2.0 升級指南" icon="arrow-up" href="https://github.com/laravel/cpx/blob/main/UPGRADE.md">
  1.x 到 2.x 的詳細遷移步驟。
</Card>


## Related topics

- [用 Pest PHP 開始 Laravel 測試](/zh-TW/blog/pest-introduction.md)
- [Laravel Package Skeleton — 官方套件用起始模板](/zh-TW/blog/package-skeleton-introduction.md)
- [Laravel Pennant 實務案例](/zh-TW/blog/laravel-pennant.md)
- [Crypto — AT Protocol 加密](/zh-TW/packages/laravel-bluesky/crypto.md)
- [套件自動偵測的內部結構](/zh-TW/advanced/package-discovery.md)