laravel 项目自身的 vendor/bin 目录不应加入系统 path；全局工具（如 deployer）应通过 --global 安装或使用 phar 二进制方式部署，以确保环境隔离、路径简洁且可复现。
laravel 项目自身的 vendor/bin 目录不应加入系统 path；全局工具（如 deployer）应通过 --global 安装或使用 phar 二进制方式部署，以确保环境隔离、路径简洁且可复现。
在 Laravel 开发与部署实践中，一个常见误区是将每个项目的 vendor/bin 目录硬编码进系统 PATH 环境变量（例如通过 export PATH="$PWD/vendor/bin:$PATH" 或修改 ~/.bashrc）。这种做法看似能让 dep、phpunit、pest 等命令“开箱即用”，实则违背了 Composer 的设计哲学和现代 PHP 工程的最佳实践。
✅ 正确做法：按用途区分安装范围
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 项目专属工具（如自定义 Artisan 命令、仅本项目使用的脚本） | composer require --dev some/tool（本地安装） | 二进制自动置于 vendor/bin/，仅限当前项目调用，可通过 ./vendor/bin/xxx 显式执行，无需修改 PATH。 |
| 跨项目通用 CLI 工具（如 Deployer、Laravel Installer、PHP CS Fixer） | composer global require deployer/deployer | 安装至 Composer 全局 vendor/bin（通常为 ~/.composer/vendor/bin），再将该目录加入 PATH —— 只需配置一次，安全且可复现。 |
| 追求极致轻量/隔离/跨平台 | 下载官方 PHAR 文件（如 dep.phar）并设为可执行 | bash curl -LO https://deployer.org/deployer.phar mv deployer.phar /usr/local/bin/dep chmod +x /usr/local/bin/dep 此方式不依赖 Composer，无版本冲突风险，适用于 CI/CD 或服务器部署。 |
⚠️ 注意事项与常见陷阱
不要将 ./vendor/bin 加入 PATH：
每个项目路径不同，动态追加会导致 PATH 膨胀、命令覆盖（如多个项目含同名二进制）、权限混乱，且在 Docker 或 CI 中完全不可移植。-
composer global 需谨慎配置：
确保 ~/.composer/vendor/bin 已加入 PATH（检查 echo $PATH），并推荐使用 Composer 的 config --global bin-dir 统一管理：composer config --global bin-dir ~/.local/bin export PATH="$HOME/.local/bin:$PATH" # 写入 ~/.bashrc 或 ~/.zshrc
Deployer 的运行机制不受影响：
无论通过 composer global 还是 PHAR 安装，dep 命令本身只负责解析 deploy.php 并执行远程任务，其行为与 Laravel 项目内部的 vendor/bin 完全解耦。服务器端无需额外安装 —— Deployer 默认通过 SSH 执行目标机上的 PHP 命令，你本地的 dep 只是“指挥官”。
✅ 推荐工作流（以 Deployer 为例）
-
本地全局安装（一次配置，长期受益）：
composer global require deployer/deployer "^7.0" # 确保 ~/.composer/vendor/bin 在 PATH 中
-
在 Laravel 项目中初始化部署配置：
cd your-laravel-project dep init --template=laravel # 生成 deploy.php
-
执行部署（无需进入 vendor/bin）：
dep deploy staging # 直接调用全局 dep
? 提示：若团队协作，可在项目根目录添加 .env.example 注明依赖工具及其安装方式，并配合 composer.json 的 "scripts" 字段提供快捷入口（如 "dep:deploy": "dep deploy staging"），进一步降低认知负担。
总之，路径管理的本质是职责分离：系统 PATH 应承载稳定、共享、可信的工具链；而项目 vendor/bin 是临时、私有、可丢弃的构建产物。坚持这一原则，你的 Laravel 部署将更健壮、可维护，也更容易迁移到容器化或云原生环境。
