composer scripts中如何引用二进制脚本-composer-PHP中文网

在Composer脚本中引用二进制脚本需确保路径正确和文件可执行，推荐使用vendor/bin/或自定义bin/目录，并注意跨平台兼容性与权限设置。

composer scripts中如何引用二进制脚本

在Composer脚本中引用二进制脚本，通常最直接且推荐的方式是利用Composer自动生成的

vendor/bin

登录后复制

目录，或者直接指定项目内部的

bin/

登录后复制

目录下的相对路径。这就像我们日常在命令行里敲命令一样，Composer会尝试在当前环境和指定的路径中找到并执行这些脚本。

解决方案

在Composer的

scripts

登录后复制

配置中，引用二进制脚本的核心在于路径的正确性以及脚本的可执行性。

引用Composer依赖项的二进制脚本： 如果你的二进制脚本是某个Composer依赖包提供的，那么它通常会被链接或复制到项目的
```
vendor/bin/
```
登录后复制
目录下。直接在
```
scripts
```
登录后复制
中以
```
vendor/bin/<script_name>
```
登录后复制
的形式引用即可。
```
{
    "name": "my-project/app",
    "require": {
        "phpunit/phpunit": "^9.5"
    },
    "scripts": {
        "test": "vendor/bin/phpunit --configuration phpunit.xml",
        "lint": "vendor/bin/phpcs --standard=PSR12 src/"
    }
}
```
登录后复制
这里，
```
phpunit
```
登录后复制
和
```
phpcs
```
登录后复制
都是通过Composer安装的依赖包提供的二进制脚本。
引用项目自定义的二进制脚本： 对于你项目内部自己开发的，不作为Composer依赖包发布的二进制脚本，一个常见的做法是在项目根目录下创建一个
```
bin/
```
登录后复制
目录来存放它们。然后在
```
scripts
```
登录后复制
中以
```
bin/<script_name>
```
登录后复制
的相对路径引用。
```
{
    "name": "my-project/app",
    "scripts": {
        "deploy": "bin/deploy-script.sh",
        "cleanup": "php bin/cleanup.php"
    }
}
```
登录后复制
请确保
```
bin/deploy-script.sh
```
登录后复制
和
```
bin/cleanup.php
```
登录后复制
文件具有执行权限（
```
chmod +x bin/deploy-script.sh
```
登录后复制
）。对于PHP脚本，直接用
```
php
```
登录后复制
解释器调用通常更稳妥，例如
```
php bin/cleanup.php
```
登录后复制
。
利用环境变量或
```
bin-dir
```
登录后复制
配置： Composer允许你通过
```
config.bin-dir
```
登录后复制
自定义二进制文件的存放位置，例如将其设置为
```
./tools
```
登录后复制
。但无论如何，在
```
scripts
```
登录后复制
中引用时，你仍然需要提供正确的相对路径。
```
{
    "name": "my-project/app",
    "config": {
        "bin-dir": "tools"
    },
    "require": {
        "phpstan/phpstan": "^1.9"
    },
    "scripts": {
        "analyze": "tools/phpstan analyze src/"
    }
}
```
登录后复制
这种方式其实只是改变了
```
vendor/bin
```
登录后复制
的默认位置，核心逻辑不变。

为什么我的Composer脚本找不到二进制文件？

这确实是一个让人头疼的问题，尤其是在初次设置或迁移项目时。我个人就遇到过好几次，明明文件就在那，Composer却报告找不到命令。这背后的原因往往比想象中要简单，但又容易被忽视。

首先，最常见的原因是路径不正确。Composer执行脚本时，它会像一个普通的shell一样，尝试在当前工作目录（通常是

composer.json

登录后复制

所在的目录）以及系统的

PATH

登录后复制

环境变量中寻找命令。如果你的脚本是

vendor/bin/phpunit

登录后复制

，但你写成了

phpunit

登录后复制

（而

vendor/bin

登录后复制

不在系统的

PATH

登录后复制

中），或者写错了路径，比如

bin/vendor/phpunit

登录后复制

，那肯定会报错。所以，检查路径是否精确无误，是第一步。

其次，文件权限。在Linux或macOS这类类Unix系统中，脚本文件必须具有可执行权限（

chmod +x <script_file>

登录后复制

）才能被直接当作命令执行。如果你创建了一个

bin/my-script.sh

登录后复制

，但忘记了给它

+x

登录后复制

权限，Composer在尝试执行时就会失败。Windows系统虽然没有直接的执行权限概念，但如果脚本依赖于特定的解释器（如

php.exe

登录后复制

、

node.exe

登录后复制

），那么解释器本身以及脚本文件的关联性也很重要。

再者，

composer.json

登录后复制

中的
bin-dir
登录后复制
配置。如果你的项目自定义了

config.bin-dir

登录后复制

，比如设置成了

./tools

登录后复制

，那么原本应该在

vendor/bin

登录后复制

下的二进制文件就会被放到

./tools

登录后复制

下。如果你在脚本中仍然按照默认的

vendor/bin/

登录后复制

路径去引用，那自然是找不到的。务必确保你的脚本引用路径与

bin-dir

登录后复制

的实际配置相符。

最后，环境问题。有时，脚本可能依赖于某些环境变量，或者需要特定的shell环境才能正确运行。例如，一个Node.js脚本可能需要

node

登录后复制

命令在

PATH

登录后复制

中，或者一个Python脚本需要

python

登录后复制

解释器。如果Composer运行的环境与你手动执行命令的环境不完全一致，也可能导致找不到命令。这时，你可能需要显式地在Composer脚本中指定解释器，比如

php bin/my-script.php

登录后复制

，而不是仅仅

bin/my-script.php

登录后复制

。

调试时，我通常会先尝试在命令行中手动执行一遍Composer脚本中引用的命令，看看是否能成功。如果能，那问题可能出在Composer的执行环境或

composer.json

登录后复制

的配置上；如果不能，那问题就更基础，可能是脚本本身、路径或权限的问题。

如何管理项目自定义的二进制脚本，而不是依赖项的？

管理项目自己的二进制脚本，与管理通过Composer安装的依赖项二进制文件有所不同。依赖项的二进制文件由Composer自动处理并放置到

vendor/bin

登录后复制

（或自定义的

bin-dir

登录后复制

）中，我们只需引用即可。但对于项目内部开发的，用于自动化构建、部署、测试或其他特定任务的脚本，我们需要一套更灵活、更贴合项目实际的策略。

我的经验是，在项目根目录创建一个专门的

bin/

登录后复制

目录，是一个非常清晰且被广泛接受的做法。这个

bin/

登录后复制

目录可以存放各种类型的脚本：Shell脚本（

.sh

登录后复制

）、PHP脚本（

.php

登录后复制

）、Python脚本（

.py

登录后复制

）甚至是Node.js脚本（

.js

登录后复制

）。这样做的好处是显而易见的：

Kits AI

Kits.ai 是一个为音乐家提供一站式AI音乐创作解决方案的网站，提供AI语音生成和免费AI语音训练

413

查看详情

隔离性好： 项目的自定义工具与Composer管理的第三方工具泾渭分明，便于维护。
易于版本控制：
```
bin/
```
登录后复制
目录直接受项目版本控制，所有团队成员都能获得相同的工具集。
引用直观： 在
```
composer.json
```
登录后复制
的
```
scripts
```
登录后复制
中，直接使用
```
bin/<script_name>
```
登录后复制
这样的相对路径，非常直观。

举个例子，假设你有一个用于项目部署的Shell脚本

deploy.sh

登录后复制

和一个用于数据清理的PHP脚本

cleanup.php

登录后复制

。

my-project/
├── composer.json
├── src/
├── tests/
└── bin/
    ├── deploy.sh
    └── cleanup.php

登录后复制

在

composer.json

登录后复制

中，你就可以这样引用它们：

{
    "name": "my-project/app",
    "scripts": {
        "deploy": "bin/deploy.sh",
        "clean:data": "php bin/cleanup.php"
    }
}

登录后复制

需要强调的是，对于Shell脚本，务必确保它具有可执行权限：

chmod +x bin/deploy.sh

登录后复制

。对于PHP脚本，虽然不强制

+x

登录后复制

权限，但通过

php bin/cleanup.php

登录后复制

显式调用解释器是一个好习惯，它能确保脚本总是由预期的PHP版本执行，避免了系统

PATH

登录后复制

中可能存在的多个PHP版本带来的混淆。

此外，你也可以考虑在

bin/

登录后复制

目录中放置一些引导脚本（wrapper scripts）。例如，如果你有一个复杂的PHP命令行工具，你可以写一个简单的Shell脚本来调用它，处理一些环境变量设置或参数传递，然后再由Composer脚本调用这个Shell引导脚本。这能增加灵活性，让核心逻辑保持简洁。

跨平台兼容性在Composer二进制脚本引用中需要注意什么？

跨平台兼容性是我们在编写Composer脚本时一个不得不面对的现实。尤其是在团队成员使用不同操作系统（Windows、Linux、macOS）时，如果不加注意，一个在Linux上运行良好的脚本可能在Windows上寸步难行。这不仅仅是路径分隔符的问题，更深层次的是命令执行机制的差异。

最明显的差异体现在脚本解释器和文件扩展名上。

在Linux和macOS上，一个脚本文件（如

.sh

登录后复制

、

.php

登录后复制

、

.py

登录后复制

）可以通过“shebang”（

#!

登录后复制

）行来指定解释器，例如

#!/usr/bin/env php

登录后复制

。只要文件有执行权限，系统就能直接运行它，无需显式指定解释器。Composer脚本中直接写

bin/my-script.php

登录后复制

通常也能工作。

然而，在Windows上，文件扩展名扮演了更重要的角色。

.bat

登录后复制

、

.cmd

登录后复制

、

.ps1

登录后复制

是Windows原生的脚本类型，它们有自己的执行方式。PHP脚本通常需要通过

php.exe

登录后复制

来执行。Composer在处理

vendor/bin

登录后复制

中的二进制文件时，会很智能地为Windows用户生成

.bat

登录后复制

和

.cmd

登录后复制

的包装器脚本。这意味着，如果你安装了

phpunit/phpunit

登录后复制

，在Linux上是

vendor/bin/phpunit

登录后复制

，在Windows上，除了

vendor/bin/phpunit

登录后复制

（可能是一个PHP文件，需要

php.exe

登录后复制

调用）外，还会生成

vendor/bin/phpunit.bat

登录后复制

和

vendor/bin/phpunit.cmd

登录后复制

。

因此，在Composer脚本中引用时：

尽量避免硬编码文件扩展名：如果你引用的是一个PHP脚本，并且它带有shebang行，或者Composer会为其生成跨平台包装器，那么在
```
composer.json
```
登录后复制
中最好只写文件名，例如
```
vendor/bin/phpunit
```
登录后复制
或
```
bin/my-php-script
```
登录后复制
。Composer会根据操作系统环境选择合适的执行方式。
```
{
    "scripts": {
        "test": "vendor/bin/phpunit"
    }
}
```
登录后复制
这样，在Linux上可能直接执行
```
vendor/bin/phpunit
```
登录后复制
，在Windows上Composer会通过
```
vendor/bin/phpunit.bat
```
登录后复制
或
```
vendor/bin/phpunit.cmd
```
登录后复制
来调用。
显式指定解释器以确保兼容性：对于项目自定义的脚本，如果担心shebang或Composer的自动处理不够健壮，或者希望明确指定解释器版本，那么显式地在Composer脚本中调用解释器是一个更安全的做法。
```
{
    "scripts": {
        "run-php-script": "php bin/my-script.php",
        "run-node-script": "node bin/my-node-script.js"
    }
}
```
登录后复制
这样，无论在哪个操作系统，只要
```
php
```
登录后复制
或
```
node
```
登录后复制
命令在系统的
```
PATH
```
登录后复制
中，脚本就能被正确执行。这在一定程度上牺牲了一点简洁性，但换来了更高的可靠性。
路径分隔符： Composer脚本在内部会处理路径分隔符的差异，所以在
```
composer.json
```
登录后复制
中使用正斜杠
```
/
```
登录后复制
通常是安全的，Composer会将其转换为操作系统对应的分隔符。