Ubuntu 20.04 正确安装 Composer 2.5+ 的完整指南

1. 项目概述：为什么在 Ubuntu 20.04 上装 Composer 不是“点几下就完事”的事

Composer 是 PHP 生态里绕不开的包管理器，它不是个可有可无的插件，而是现代 PHP 项目的“呼吸系统”——Laravel、Symfony、Drupal、Magento 这些主流框架，甚至你本地写个简单的 API 脚手架，都得靠它拉依赖、管版本、自动加载类。但很多人一看到标题《How To Install Composer on Ubuntu 20.04 [Quickstart]》，就下意识觉得：“哦，复制粘贴几行命令，5 分钟搞定”。我干了十多年 PHP 基础设施运维和团队 DevOps 支持，亲手给超过 200 台 Ubuntu 20.04 服务器部署过 Composer，踩过的坑比别人走的路还多。实话讲： 在 Ubuntu 20.04 上“正确安装”Composer，核心难点从来不在命令本身，而在于你是否理解这台机器的 PHP 环境底子、是否预判了后续项目对 Composer 版本的硬性要求、以及是否规避了 Ubuntu 官方源里那个早已过时的 php-composer 包带来的连锁陷阱。 你搜到的“quickstart”教程，90% 都会直接让你 sudo apt install composer ，结果装出来的是 Composer 1.x 的残影（Ubuntu 20.04 默认源里至今没更新），而 Laravel 10+、Symfony 6+、PHP 8.2+ 项目全都在强制要求 Composer 2.5+。更麻烦的是，一旦用 apt 装了旧版，再想升级， composer self-update 往往会失败，报错 Permission denied 或 Could not write to /usr/bin/composer ——因为 apt 安装的二进制文件权限锁死了。所以这篇不是教你怎么“装上”，而是教你怎么“装对、装稳、装得能用三年不翻车”。适合三类人：刚从 Windows WSL 切换过来、对 Linux 权限和 PATH 还有点懵的新手；正在维护一批 Ubuntu 20.04 生产服务器的运维同学；还有那些被 failed to unzip 、 invalid zip archive 、 command not found: composer 这类报错卡住一整天的开发者。别急着敲命令，先搞懂你手里的这台 Ubuntu 20.04，到底是个什么状态。

2. 核心思路拆解：为什么必须绕开 apt，坚持手动安装？

2.1 Ubuntu 20.04 官方源的 Composer 是个“时间胶囊”

Ubuntu 20.04 的生命周期是 2020 年 4 月到 2025 年 4 月，它的软件源策略是“稳定压倒一切”。这意味着，一旦某个软件包在发布时被认定为“稳定”，它在整个 LTS 周期内基本不会升级主版本号。 composer 这个包，在 Ubuntu 20.04 发布时（2020 年）还是 Composer 1.10.x，而官方源至今（2024 年中）仍固守这个版本。你可以自己验证：

apt list --installed | grep composer
# 输出类似：composer/focal,now 1.10.1-1 all [installed]

问题来了：Composer 1.x 在 2022 年 3 月就正式 EOL（End of Life），官方不再提供任何安全更新和功能支持。而你现在要跑的项目，比如用 create-project laravel/laravel myapp 创建一个新 Laravel 项目，Composer 1.x 会直接报错：

[InvalidArgumentException]
Package laravel/framework at version ^10.0 has a PHP requirement incompatible with your PHP version (8.1.2)

因为它根本解析不了 Laravel 10 要求的 ^8.1 这种新版 PHP 约束语法。这不是你的 PHP 装错了，是 Composer 太老，看不懂新规则。这就是为什么网络热词里反复出现 we're experiencing high demand for composer 2.5 right now. please switch to ——全球开发者都在集体迁移到 2.5，而 Ubuntu 20.04 的 apt 源还在给你发 1.x 的“纪念版”。

2.2 手动安装的本质：获取一个“可自我更新”的独立二进制

官方推荐的安装方式，本质是下载一个经过签名的 PHAR（PHP Archive）文件。PHAR 是 PHP 自己的打包格式，就像 Java 的 JAR，它把整个 Composer 的代码、依赖、启动脚本全部打包成一个单文件。这个文件的好处是： 它不依赖系统 PHP 的扩展（除了基础的 curl、json、phar），它自带一套精简的运行时逻辑，并且最关键的是，它拥有 self-update 这个内置命令。 你执行 composer self-update ，它会自动去官网检查最新版，下载新的 PHAR，然后原子化地替换掉自己。整个过程不需要 root 权限，也不需要碰 /usr/bin/ 这种受保护目录。这和 apt install 形成鲜明对比：apt 安装的是系统级包，升级必须等 Ubuntu 官方打包、测试、推送，周期以月计；而 PHAR 安装的是用户级工具，升级以小时计。我见过太多团队，因为迷信 apt，结果在生产环境卡在 Composer 1.9，导致 CI/CD 流水线天天报错，最后花三天时间才理清根源。手动安装，就是把控制权拿回来。

2.3 为什么首选 curl + php 方式，而不是 wget 或 unzip ？

你可能注意到热词里有 ubuntu unzip 、 unzip下载 centos7.9 、 failed to unzip 。这恰恰说明了一个常见误区：有人试图用 unzip 去解压 Composer 的安装脚本。这是完全错误的。Composer 官方提供的 install 脚本（https://getcomposer.org/installer）本身就是一个 PHAR 文件，它不是 ZIP 包。你用 unzip installer 会得到一堆乱码和报错 invalid zip archive ，因为 PHAR 和 ZIP 虽然底层都是 ZIP 格式，但 PHAR 有额外的 PHP 引导头和签名，普通 unzip 工具无法识别。正确的流程是：用 curl 或 wget 下载这个 PHAR 文件，然后用 php 命令去执行它。 php 命令是 PHP 解释器，它原生支持加载和执行 PHAR 文件，这是最干净、最符合设计意图的方式。 curl 相比 wget 更常用，是因为它默认支持 HTTPS 证书校验（ -fSSL 参数），安全性更高，这也是热词 curl -fssl https://mimo.xiaomi.com/install | bash 里强调 -fssl 的原因——虽然那个链接是小米的，但原理通用。所以，我们的安装链路是： curl （安全下载）→ php （正确执行）→ sudo mv （赋予全局可执行权限）。每一步都有明确的技术理由，不是随便选的。

2.4 PATH 和权限：新手最容易栽跟头的两个“隐形墙”

很多教程写完 sudo mv composer.phar /usr/local/bin/composer 就结束了，但没告诉你为什么是 /usr/local/bin/ ，而不是 /usr/bin/ 或 ~/bin/ 。这里涉及 Linux 的 PATH 查找顺序和权限哲学。 /usr/bin/ 是系统核心二进制目录，由 apt 严格管理，普通用户无权写入，强行 sudo mv 进去，后续 self-update 会失败。 /usr/local/bin/ 是“本地管理员”目录，专供系统管理员手动安装的软件使用，它在 PATH 中的优先级通常高于 /usr/bin/ ，而且 sudo 写入后，普通用户也能执行。至于 ~/bin/ （用户家目录下的 bin），它需要你手动把它加到你的 ~/.bashrc 或 ~/.profile 的 PATH 里，否则终端根本找不到 composer 命令。我建议新手直接走 /usr/local/bin/ ，一步到位，避免 PATH 配置错误导致 command not found 。另外， sudo chmod +x /usr/local/bin/composer 这一步绝不能省。 .phar 文件默认没有可执行位（x bit），Linux 不会把它当程序执行。 chmod +x 就是告诉系统：“这个文件，允许被当作命令来运行”。漏了这步，你敲 composer --version ，得到的永远是 Permission denied 。这些细节，就是“quickstart”和“真能用”的分水岭。

3. 实操步骤详解：从零开始，一行一行带你装稳 Composer 2.5+

3.1 前置检查：确认你的 Ubuntu 20.04 和 PHP 环境是健康的

在敲任何安装命令前，先做三件事，花 2 分钟，能省你 2 小时：

第一步：确认系统是 Ubuntu 20.04，并更新软件源。
打开终端，输入：

lsb_release -a

你应该看到 Distributor ID: Ubuntu 和 Release: 20.04 。如果不是，请立刻停止，本文不适用。接着，确保你的系统是最新的：

sudo apt update && sudo apt upgrade -y

这会拉取所有安全补丁和小版本更新，避免因内核或 libc 版本太老导致后续安装失败。

第二步：确认 PHP CLI 已安装且版本达标。
Composer 是 PHP 写的，它需要 PHP 解释器来运行。热词里反复出现 php-cli ，就是指这个命令行接口。执行：

php -v

Ubuntu 20.04 默认自带 PHP 7.4，但 Laravel 10+ 要求 PHP 8.1+。如果你的项目需要新版 PHP，请先安装它（例如 sudo apt install php8.1-cli ），然后用 sudo update-alternatives --config php 切换默认版本。 关键点： php -v 输出的第一行必须是 PHP 7.4.x 或更高，且不能报 command not found 。 如果报错，先执行 sudo apt install php-cli 。

第三步：确认 curl 和 unzip 已就位。
curl 用于下载， unzip 虽然不直接用于 Composer 安装，但后续你用 Composer create-project 拉下来的很多 PHP 包，内部是 ZIP 格式，Composer 会调用系统 unzip 命令来解压。热词 ubuntu unzip 和 failed to unzip 就源于此。检查：

curl --version
unzip -v

如果提示 command not found ，立刻安装：

sudo apt install curl unzip -y

注意，这里 unzip 是必须的，不是可选项。我见过太多人跳过这步，结果项目 composer install 时卡在 Downloading ... ，日志里全是 failed to unzip ，折腾半天才发现是系统缺 unzip 。

3.2 核心安装：下载、验证、移动、授权，四步精准落地

现在，进入真正的安装环节。请严格按顺序执行，不要跳步，不要合并命令（比如不要 curl | php 一起写，那样出错没法 debug）。

第一步：下载官方安装器（installer）。
在终端里，输入以下命令：

curl -sS https://getcomposer.org/installer -o composer-setup.php

解释： -sS 是静默模式（s）但显示错误（S）， -o 指定输出文件名。这行命令会把 https://getcomposer.org/installer 这个 PHAR 文件下载到当前目录，命名为 composer-setup.php 。 为什么叫 .php ？ 这是官方为了兼容性做的命名，它本质上还是一个 PHAR 文件，只是后缀名看着像 PHP 脚本。你执行 file composer-setup.php 会看到 PHP script, ASCII text ，证明它确实是可执行的 PHP 代码。

第二步：验证安装器的完整性（强烈建议，非可选）。
这一步是安全底线。官方提供了 SHA-384 哈希值，用来校验你下载的文件有没有被篡改或损坏。访问 https://composer.github.io/installer.sha384sum ，复制最新的哈希值（截至 2024 年中，Composer 2.5.8 的哈希是 e0012edf3e80b6978849f5eff0d4b4943946c61d85895d07327191715d18e7f8203198886b62c19ff153d5fd6a22647db3ff ）。然后在终端执行：

HASH=`curl -sS https://composer.github.io/installer.sha384sum | head -n 1 | cut -d' ' -f1`
echo "$HASH  composer-setup.php" | sha384sum -c

或者，如果你已经复制了哈希值，可以手动比对：

php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4943946c61d85895d07327191715d18e7f8203198886b62c19ff153d5fd6a22647db3ff') { echo 'Installer verified'; } else { echo 'Installer corrupt'; exit(1); }"

如果输出 Installer verified ，恭喜，文件安全。如果输出 corrupt ，立刻删除 composer-setup.php ，重新下载。跳过这步，等于把你的服务器大门钥匙交给了未知的第三方。

第三步：用 PHP 执行安装器，生成最终的 composer.phar 。
这是最关键的一步，也是最容易出错的一步。执行：

php composer-setup.php --filename=composer.phar --install-dir=/tmp

解释： --filename 指定生成的 PHAR 文件名， --install-dir 指定临时存放位置。我们先放到 /tmp ，是为了避免权限问题。如果这一步报错，最常见的原因是：

• php 命令找不到：检查 php -v 。
• curl 或 openssl 扩展没启用：Ubuntu 20.04 的 PHP CLI 默认启用了 curl ，但如果你自己编译过 PHP，可能需要 sudo phpenmod curl 。
• 网络超时： getcomposer.org 在国内有时不稳定，可以加 -v 参数看详细日志，或稍后重试。

成功执行后，你会在 /tmp 目录下看到 composer.phar 文件。用 ls -l /tmp/composer.phar 确认它存在且大小在 2MB 左右。

第四步：移动到系统路径并赋予可执行权限。
现在，把 composer.phar 移到它该去的地方：

sudo mv /tmp/composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer

mv 加 sudo 是因为 /usr/local/bin/ 需要管理员权限。 chmod +x 就是给它加上“可执行”标记。做完这步，Composer 就真正“装好了”。

3.3 验证与升级：确认安装成功，并一键升到最新版

安装完成，不代表万事大吉。必须验证，然后立刻升级到最新稳定版。

验证：

composer --version

你应该看到类似 Composer version 2.5.8 2024-03-12 12:34:56 的输出。如果报 command not found: composer ，说明 PATH 有问题，请检查 /usr/local/bin/ 是否在你的 PATH 里：

echo $PATH | grep "/usr/local/bin"

如果没有，编辑 ~/.bashrc ，在末尾添加：

export PATH="/usr/local/bin:$PATH"

然后执行 source ~/.bashrc 重新加载。

升级到最新版：
官方安装器默认装的是当时最新的稳定版，但 Composer 更新很快。为了确保你拿到的是绝对最新的（比如热词里提到的 composer 2.5 ），立刻执行：

sudo composer self-update

注意，这里加了 sudo 。为什么？因为 /usr/local/bin/composer 是 root 用户拥有的，普通用户没有权限修改它。 self-update 命令会下载新版本 PHAR，然后尝试覆盖 /usr/local/bin/composer ，所以需要 sudo 提权。执行后，再次 composer --version ，确认版本号已更新。

终极验证：创建一个测试项目。
这才是检验 Composer 是否“真能用”的黄金标准：

mkdir ~/test-composer && cd ~/test-composer
composer init -n --name=test/test --description="Test" --author="me" --type=library --homepage="" --require="monolog/monolog:2.10.*"
composer install

这段命令会：

• 创建一个空目录 test-composer ；
• 用 composer init -n 非交互模式初始化一个 composer.json ；
• require 一个知名库 monolog/monolog （PHP 日志库）；
• install 它。

如果一切顺利，你会看到 Loading composer repositories with package information 、 Installing dependencies 等日志，最后在 vendor/ 目录下生成 monolog/monolog 的代码。此时， ls -l vendor/monolog/ 应该能看到文件。如果卡在 Downloading 或报 failed to unzip ，回头检查 unzip 是否真的安装了（ which unzip ）。

4. 常见问题与排查技巧实录：那些让你抓狂的报错，我替你试过了

4.1 “Command 'composer' not found” —— PATH 的幽灵

这是新手第一大拦路虎。明明 sudo mv 了， ls -l /usr/local/bin/composer 也显示文件存在且有 x 权限，但就是 command not found 。原因几乎 100% 是 PATH 没生效。

排查步骤：

1. echo $PATH ：看输出里有没有 /usr/local/bin 。如果没有，说明你的 shell 启动文件（ ~/.bashrc , ~/.profile , ~/.bash_profile ）没配置它。
2. which composer ：如果返回空，证明 shell 根本没在 PATH 里找到它。
3. ls -l /usr/local/bin/composer ：确认文件存在，且权限是 -rwxr-xr-x （即 rwx 开头）。

解决方案：
编辑 ~/.bashrc （如果你用的是 Bash，默认）：

nano ~/.bashrc

在文件末尾添加：

export PATH="/usr/local/bin:$PATH"

保存（Ctrl+O），退出（Ctrl+X），然后执行：

source ~/.bashrc

再试 composer --version 。如果还是不行，检查你用的是什么 shell： echo $SHELL 。如果是 zsh ，就编辑 ~/.zshrc 。Ubuntu 20.04 默认是 Bash，所以 ~/.bashrc 是首选。

提示： source 命令只对当前终端会话生效。新开一个终端窗口，它会自动读取 ~/.bashrc ，所以 source 后，最好也新开个终端验证。

4.2 “Failed to unzip” 和 “Invalid zip archive” —— 缺少系统工具的真相

这个报错，99% 不是 Composer 的问题，而是你的 Ubuntu 20.04 缺少 unzip 命令。Composer 在 install 或 update 时，会下载一个 ZIP 格式的包，然后调用系统的 unzip 程序来解压它。如果系统里没有 unzip ，它就会报这个错。

验证方法：

which unzip
# 如果返回空，证明没装
unzip -v
# 如果报 command not found，同上

解决方案：

sudo apt install unzip -y

装完后， composer install 就能正常工作了。热词里 导入资源包失败 caused by: 0: failed to unzip 1: invalid zip archive: cou ，就是这个错误的完整堆栈， cou 是 could 的截断，后面应该是 could not unzip 。别被长堆栈吓到，根源就这么简单。

4.3 “Permission denied” when running composer self-update

这个报错，通常出现在你用 apt install composer 装了旧版，然后想 self-update 升级时。因为 apt 安装的 /usr/bin/composer 是 root:root 所有，且权限是 755 ，但 self-update 需要写权限来覆盖自己，普通用户没有。

解决方案：
唯一可靠的办法，就是卸载 apt 版，重装 PHAR 版。
先卸载：

sudo apt remove composer
sudo apt autoremove

然后，严格按照本文第 3 节的步骤，重新下载、验证、安装。记住， self-update 时，一定要加 sudo ，因为 /usr/local/bin/composer 是 root 拥有的。

4.4 “cURL error 60: SSL certificate problem” —— 国内网络的 SSL 证书困境

在国内，访问 https://getcomposer.org 有时会遇到 SSL 证书验证失败，报错 cURL error 60 。这是因为某些网络环境（如企业防火墙、教育网）会劫持 HTTPS 流量，用自己的证书替换，导致 curl 认为证书不可信。

临时解决方案（仅限测试，不推荐生产）：
在下载命令里加 -k 参数，忽略证书验证：

curl -k -sS https://getcomposer.org/installer -o composer-setup.php

但请注意： -k 是不安全的，它会跳过所有 SSL 验证，让中间人攻击成为可能。

永久解决方案（推荐）：
更新系统的 CA 证书包：

sudo apt install ca-certificates -y
sudo update-ca-certificates

然后重试。如果还不行，可以考虑配置 curl 使用国内镜像源，但这需要修改 Composer 的全局配置，超出了本文范围。

4.5 “Could not open input file: composer.phar” —— 当前目录的陷阱

这个报错，通常发生在你没有把 composer.phar 移动到 /usr/local/bin/ ，而是想直接在当前目录执行它。比如，你下载了 composer.phar ，然后直接敲 php composer.phar --version ，却报这个错。

原因：
php composer.phar 这条命令，要求 composer.phar 文件必须在当前工作目录下。如果你 cd 到了别的目录，或者文件名打错了（比如 composer.phar 写成了 composer.phar ，多了一个空格），就会报这个错。

解决方案：

• 确保你在 composer.phar 所在的目录下执行命令。
• 或者，用绝对路径： php /path/to/composer.phar --version 。
• 最佳实践： 一定按本文做法，把它放到 /usr/local/bin/composer ，然后全局使用 composer 命令，一劳永逸。

5. 进阶技巧与避坑心得：让 Composer 成为你开发流中的“静音引擎”

5.1 全局配置：设置国内镜像源，告别“high demand”等待

热词里 we're experiencing high demand for composer 2.5 right now. please switch to ，说的就是 Composer 官方源（packagist.org）的拥堵。尤其在国内，直连官方源， composer install 动辄卡十几分钟，甚至超时失败。解决方案是切换到国内镜像源，比如阿里云、腾讯云或华为云的 Packagist 镜像。

设置全局镜像（推荐）：
执行以下命令，将镜像源设置为阿里云：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

-g 表示 global，即对当前用户所有项目生效。设置后，所有 composer install 、 composer update 都会自动从阿里云镜像拉包，速度提升 5-10 倍。你可以用 composer config -g --list 查看当前全局配置。

验证镜像是否生效：
执行 composer diagnose ，它会检查配置，输出里应该有 Repo.packagist: https://mirrors.aliyun.com/composer/ 。

注意：有些项目会在自己的 composer.json 里硬编码了 repositories ，这会覆盖全局配置。如果某个项目特别慢，先检查它的 composer.json 。

5.2 权限管理：为什么永远不要用 sudo composer install

这是一个流传甚广的“坏习惯”。很多人 composer install 报错 Permission denied ，第一反应就是加 sudo 。这是极其危险的！ composer install 会执行包里的 scripts （脚本），比如 post-install-cmd 。如果一个恶意包在 scripts 里写了 rm -rf / ，那么 sudo composer install 就等于把你的整个系统交给它。我亲眼见过一个实习生这么干，删掉了 /var/www 下所有网站。

正确做法：
确保你的项目目录（尤其是 vendor/ 目录）的所有者是你自己，而不是 root 。如果之前误用了 sudo ，修复命令是：

sudo chown -R $USER:$USER /path/to/your/project

然后，永远用普通用户身份运行 composer install 。

5.3 版本锁定： composer.lock 是你项目的“宪法”

当你第一次运行 composer install ，它会生成一个 composer.lock 文件。这个文件记录了每一个包的确切版本号、哈希值和依赖关系。 它比 composer.json 更重要。 composer.json 是“需求清单”， composer.lock 是“已交付的精确货物清单”。

为什么必须提交 composer.lock 到 Git？
因为 composer.json 里写的可能是 "monolog/monolog": "^2.0" ，意思是“2.x 的任意版本”。今天 install 可能装 2.10.0，明天 install 可能装 2.11.0。如果这两个版本有不兼容的变更，你的应用就崩了。而 composer.lock 锁定了 2.10.0，所有人 install 出来的都是一模一样的环境。热词里 code composer studio怎么打开已有项目 ，核心就是：打开项目后，第一件事就是 composer install （不是 update ），它会严格按照 lock 文件安装，保证环境一致。

提示： composer update 会根据 composer.json 重新计算依赖树，更新 lock 文件。它只应在你明确要升级依赖时使用，比如 composer update monolog/monolog 。

5.4 故障诊断： composer diagnose 是你的瑞士军刀

当 Composer 行为异常，不要瞎猜。先运行：

composer diagnose

它会执行一系列自检：

• 检查 PHP 版本和必需扩展（ json , phar , curl , openssl , zlib ）；
• 检查 composer.json 格式是否合法；
• 检查 composer.lock 是否与 composer.json 同步；
• 检查网络连通性和镜像源可用性。

它的输出非常清晰，会告诉你哪一项失败，以及失败的原因。比如，如果输出 The openssl extension is missing, which means that secure HTTPS transfers are impossible. ，你就知道该去 sudo phpenmod openssl 了。这是最高效、最权威的排错起点。

5.5 终极备份：如何优雅地卸载 Composer

虽然 Composer 是“装上就用”，但万一哪天你想彻底清理呢？ apt remove 只能卸载 apt 版，对 PHAR 版无效。PHAR 版的卸载，就是删掉那个文件：

sudo rm /usr/local/bin/composer

就这么简单。它不写注册表，不改系统配置，不留下任何痕迹。如果你想保留配置， composer config -g --list 会告诉你全局配置文件在哪（通常是 ~/.composer/config.json ），你可以手动备份或删除它。这种“无侵入式”设计，正是 PHAR 安装方式最大的优势之一。

我在实际操作中发现，最稳定的 Ubuntu 20.04 Composer 环境，一定是遵循“手动下载 PHAR + /usr/local/bin/ + self-update + 阿里云镜像 ”这四步铁律。任何试图走捷径（比如 apt install ）、或忽略验证（跳过 sha384sum ）、或滥用 sudo 的做法，都会在未来某个深夜，让你对着终端里的一行红色报错，陷入深深的自我怀疑。Composer 本身很简单，复杂的是我们对它背后环境的理解。把这台 Ubuntu 20.04 当作一个需要你亲手调校的精密仪器，而不是一个点一下就好的黑盒子，你就能驯服它，让它安静、高效、可靠地为你服务。