3.8. 故障排除

优质

小牛编辑

134浏览

2023-12-01

一般

在询问任何人之前, 请先运行 composer diagnose 检查是否存在常见问题。如果全部检出，请继续执行后续步骤。
使用 Composer 遇到任何问题时，请务必使用最新版本。有关详细信息请参阅 self-update
通过运行安装程序的检查，确保您的设置没有问题 curl -sS https://getcomposer.org/installer | php -- --check.
确保您直接从您的安装厂商 composer.json 通过 rm -rf vendor && composer update -v 障排除时，不包括与现有供应商的装置或任何可能的干扰 composer.lock 项。
尝试通过运行清除 Composer 的缓存 composer clear-cache。

包没有找到

仔细检查确保在你的 composer.json 中没有拼写或者库分支和标签的名字错误。
一定要设置正确最小稳定性。开始或一定没有问题，设置 最小稳定性 为 "开发"。
包不是来自 Packagist包镜像站而是应该通常在根包中被定义（包取决于所有供应商）。
使用相同的供应商和包名称在您的存储库的所有分支和标签,尤其是当维护第三方分支和使用 替换 时。
如果你更新到最近推出的版本的包，请注意，Packagist 包镜像站有 1 分钟左右延迟在新包于 Composer 中是可见的之前。
如果你更新一个包，它可能取决于更新的版本。在这种情况下，添加 --with-dependencies 参数或添加命令需要一个更新的所有依赖项。

在 https://www.yii-china.com/doc/detail/travis-ci.org 中找不到依赖包

检查上面 "找不到依赖包" 的选项。
如果测试的软件包是其依赖项之一（循环依赖项）的依赖项，则问题可能是 Composer 无法正确检测到软件包的版本号导致的。如果它是通过 Git 克隆下来的，那么它通常是正常的，Composer 将检测当前分支的版本号，但是 travis 执行的是浅克隆，因此在测试拉取请求和特征分支时，进程可能会失败。最好的解决方式是通过在环境变量中使用常量比如 COMPOSER_ROOT_VERSION 来定义你所使用的版本号，例如，将其根软件包的版本定义为 dev-master，使用： before_script: COMPOSER_ROOT_VERSION=dev-master composer install 导出调用 Composer 的变量。

Jenkins 构建时包找不到

查看官方『包找不到』异常项。
类似于包找不到这样的失败原因常出现在持续集成过程中： Jenkins 在 git-clone / checkout 时将分支设置在『脱离头部』的状态。这样的结果是： Composer 无法识别当前拉取的分支的版本，并且可能无法解析包的循环依赖关系。为了解决这个问题，你可以为Jenkins脚本的Git设置添加附加行为（拉取指定的分支），你指定的分支应该和你将要拉取的分支相同。这样的话，checkout 时不会在脱离头部的状态并且也可以正确的识别包之间的依赖关系。

我在 `composer.json` 里面定义了一个含有包的依赖关系，但它好像没有生效。

包 的相关参数配置在根目录的 composer.json 中。他们是不能被继承的。你可以通过阅读『why can't composer load repositories recursively?』这篇文章了解原因。解决这个问题的最简单的方法就是在项目根目录下的 composer.json 中删除或者重新定义想引用的包。

我已经锁定一个依赖特定的 commit 但得到意想不到的结果。

虽然 Composer 支持依赖锁定到一个特定的 commit 使用 #commit-ref 语法，有一些警告，每个人都应该考虑到。最重要的是记录, 但是经常被忽视:

注意：虽然这是方便的，它不应该如何使用包从长远来看，因为它有技术限制。 composer.json 元数据仍将从您指定的分支机构名称前的散列读取。因为在某些情况下，它将不是一个实际的解决方法，只要可以你应该总是试图切换到标记的版本就。

没有这个限制的简单方法。因此,强烈建议您不要使用它。

需要重写包版本

假设你的项目依赖于软件包 A ，这又取决于包的特定版本 B (说明 0.1)。但是你需要一个不同版本的上述的包 B (说明 0.11).

您可以通过将版本0.11到0.1来解决此问题。

composer.json:

{
    "require": {
        "A": "0.2",
        "B": "0.11 as 0.1"
    }
}

更多信息请参阅别名。

内存限制错误

在某些命令中, Composer 可能会出现下面的错误：

PHP Fatal error: Allowed memory size of XXXXXX bytes exhausted <...>

在这种情况下, PHP 应该增加 memory_limit 的值。

注意: Composer 的内部增加 memory_limit 到了 1.5G。

要获取当前 memory_limit 值，请运行：

php -r "echo ini_get('memory_limit').PHP_EOL;"

试增加 php.ini 文件中的限制（例如 /etc/php5/cli/php.ini ，类似Debian 系统）：

; Use -1 for unlimited or define an explicit value like 2G
memory_limit = -1

Composer 还遵循 COMPOSER_MEMORY_LIMIT 环境变量定义的内存限制：

COMPOSER_MEMORY_LIMIT=-1 composer.phar <...>

或者，你可以使用命令行参数来增加限制：

php -d memory_limit=-1 composer.phar <...>

当激活 shell fork 炸弹保护时，cPanel 实例上也会发生此问题。有关更多信息，请参阅 cPanel 站点上的 fork bomb功能文档。

Xdebug 对 Composer 的影响

Xdebug 会对 Composer 的运行造成影响，为了提高性能，Composer 运行时会关闭 Xdebug 并重启 PHP 。您可以使用环境变量来阻止此行为： COMPOSER_ALLOW_XDEBUG=1 。

如果你的系统开启了 Xdebug ，Composer 会始终显示一个警告信息，您可以使用环境变量来重写它：COMPOSER_DISABLE_XDEBUG_WARN=1 。设置重写后，如果您还是意外地看到此警告，那么说明重启过程已经失败：请报告这个问题。

"系统无法找到指定的路径" （Windows）

打开注册表；
在 HKEY_LOCAL_MACHINE\Software\Microsoft\Command Processor ， HKEY_CURRENT_USER\Software\Microsoft\Command Processor
或 HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Command Processor 中搜索 AutoRun 键；
检查它是否包含任何不存在文件的路径，如果是这种情况，删除它们。

API 访问频率限制和 OAuth 令牌

由于 GitHub 对其 API 的访问频率做了限制， Composer 可能会提示进行身份验证，询问您的用户名和密码，以便其可以继续工作。

如果您不愿意向 Composer 提供您的 GitHub 凭据，您可以使用以下过程手动创建一个令牌：

创建 GitHub 上的 OAuth 令牌。在这里了解更多。
将其添加到运行的配置 composer config -g github-oauth.github.com <oauthtoken> 。

现在 Composer 应该在不需要身份验证的情况下就可以安装/更新。

proc_open(): 分支失败错误

如果 composer 显示 proc_open() 则在某些命令上失败:

PHP Fatal error: Uncaught exception 'ErrorException' with message 'proc_open(): fork failed - Cannot allocate memory' in phar

这可能会发生，因为 VPS 内存不足，并且没有启用交换空间。

free -m

total used free shared buffers cached
Mem: 2048 357 1690 0 0 237
-/+ buffers/cache: 119 1928
Swap: 0 0 0

若要启用交换，您可以使用例如：

/bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=1024
/sbin/mkswap /var/swap.1
/sbin/swapon /var/swap.1

可以在本教程之后制作一个永久交换文件。

降级模式

由于 Travis 和其他系统上的一些间歇性问题，我们引入了降级网络模式，帮助 Composer 成功完成，但禁用一些优化。当首次检测到问题时，会自动启用此功能。如果您偶尔看到这个问题，您可以不必担心（网络缓慢或过载也会导致超时），但是如果反复出现问题，您可能需要查看下面的选项找到原因并解决它。

如果您已经指向此页面，则需要检查以下几项：

如果您使用的是 ESET 防病毒软件，请进入 "Advanced Settings" 并禁用 "web access protection" 下的 "HTTP-scanner"
如果您使用的是 IPv6，请尝试禁用它。如果这样解决了您的问题，与您的 ISP 或服务器主机的联系，那么问题不在于 Packagist 级别，而在于您与 Packagist （即整个互联网）之间的路由规则。解决这些问题的最佳方法是，提高对有能力修复它的网络工程师的认识。请查看 IPv6 下一部分的解决方法。
如果上述方法均无效，请报告错误。

操作超时（IPv6 问题）

您如果未正确配置 IPv6 ，则可能会遇到错误。一个常见的错误是：

The "https://getcomposer.org/version" file could not be downloaded: failed to
open stream: Operation timed out

我们建议您修复 IPv6 设置，如果无法做到这一点，您可以尝试以下解决方法：

Linux 解决方法：

在 linux 上，运行此命令似乎有助于 ipv4 流量具有比 ipv6 更高的 prio , 这是比完全禁用 ipv6 更好的选择：

sudo sh -c "echo 'precedence ::ffff:0:0/96 100' >> /etc/gai.conf"

Windows 解决方法：

在 windows 上唯一的办法就是完全禁用 ipv6 （无论是在 Windows 中还是在家用路由器中）。

Mac OS X 解决方法：

获取您的网络设备的名称：

networksetup -listallnetworkservices

在该设备上禁用 IPv6 （在本例中为"Wi-Fi"）：

networksetup -setv6off Wi-Fi

运行 composer ...

您可以再次启用 IPv6 ：

networksetup -setv6automatic Wi-Fi

也就是说，如果这可以解决您的问题，请与您的 ISP 联系，以尝试解决路由错误。这是能让每个人都能解决问题的最好方法。

Composer 与 SSH ControlMaster 挂起

当您尝试从 Git 存储库安装软件包并使用 ControlMaster 设置进行 SSH 连接时， Composer 可能会无休止的挂起，并且您会在进程列表中看到处于 defunct 状态的 sh 进程。

原因是 SSH Bug：https://bugzilla.mindrot.org/show_bug.cgi?id=1988

解决方法是，在运行 Composer 之前打开与 Git 主机的 SSH 连接：

ssh -t git@mygitserver.tld
composer update

有关更多信息，请参阅 https://github.com/composer/composer/issues/4180 。

Zip 存档未正确解压

Composer 可以使用系统提供的 unzip 或者 PHP's 本身的 ZipArchive 类来解压缩。 ZipArchive 类在 Windows 上是首选。在其他 OSes 系统中 ZIP 文件可以包含权限和符号链接，所以首选 unzip ，如果您需要这些功能，建议您安装它。