Ubuntu 22.04 安装 Composer 全链路指南：依赖、权限、镜像与排错

最新推荐文章于 2026-06-21 16:40:17 发布

原创

最新推荐文章于 2026-06-21 16:40:17 发布 · 464 阅读

标签

#Composer #Ubuntu 22.04 #php-zip

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

Composer 是 PHP 生态里绕不开的命脉级工具，它不是个普通软件，而是整个现代 PHP 项目的“包管家+依赖调度中心+自动构建引擎”。你在 Ubuntu 22.04 上敲下 composer install 的那一刻，背后发生的是：解析 composer.json 中几十个包的版本约束、递归计算兼容性图谱、从 Packagist 镜像源拉取数百 MB 的 ZIP 包、校验 SHA-256 签名、解压到 vendor/ 目录、生成自动加载映射文件（ vendor/autoload.php ），最后还要确保所有类能被 PHP 解释器按 PSR-4 规范精准定位。这整套流程，任何一个环节卡住——比如你用的是 PHP 8.1 但某个老包只支持 PHP 7.4，或者系统里没装 unzip 导致解压失败，又或者 /tmp 分区只剩 20MB 空间——都会让命令停在 Loading composer repositories with package information 这一行，死活不动。我见过太多人把问题归结为“网络慢”，结果查了半小时才发现是 php-cli 没启用 openssl 扩展，连 HTTPS 请求都发不出去。Ubuntu 22.04 作为 LTS 版本，自带 PHP 8.1，但默认不装 php-zip 、 php-xml 、 unzip 这些 Composer 运行的硬性依赖，更别说国内开发者常遇到的 Packagist 源访问延迟问题。所以，“How To Install and Use Composer on Ubuntu 22.04” 这个标题，表面是安装教程，实际是一份覆盖环境诊断、依赖补全、源加速、权限规避、故障自愈的全链路实战手册。它适合三类人：刚从 Windows 转 Linux 的 PHP 新手（别再用 XAMPP 套件思维想问题）、正在部署 Laravel/ThinkPHP 项目的运维同学（得知道 composer create-project 和 --no-dev 的区别）、还有那些被 failed to unzip 或 invalid zip archive 报错折磨到凌晨两点的开发者（这篇文章会告诉你，90% 的这类错误和 ZIP 文件本身无关，而是 unzip 命令权限或 TMPDIR 环境变量惹的祸）。接下来的内容，不会教你复制粘贴几行命令就收工，而是带你亲手拆开 Composer 的运行黑箱，看清每一颗螺丝钉的位置和拧紧逻辑。

2. 环境准备与底层依赖补全：先让系统“有手有脚”，再谈干活

2.1 Ubuntu 22.04 默认 PHP 环境的真实状态

Ubuntu 22.04 LTS 官方仓库中预装的 PHP 版本是 8.1.2-1ubuntu2.14 （截至 2024 年中），这个版本本身没问题，但它的安装包是“最小化精简版”。执行 php -v 能看到版本号，但 php -m 列出的扩展列表里，大概率找不到 zip 、 xml 、 mbstring 、 curl 这几个关键模块。为什么？因为 Ubuntu 的 php8.1 主包只包含核心解释器，其他功能以独立子包形式存在，必须手动安装。这和 Windows 下 WAMP/XAMPP 一键集成所有扩展的思路完全不同——Linux 发行版信奉“职责分离”，你得自己告诉系统：“我需要解压 ZIP 包，所以请装 php8.1-zip ；我需要处理 XML 配置，所以请装 php8.1-xml ”。

提示：别急着 apt install php 。Ubuntu 22.04 的 php 元包默认指向 php8.1 ，但如果你之前手动编译过 PHP 或通过第三方 PPA 升级过， php -v 显示的版本可能和 apt list --installed | grep php 查到的不一致。务必先统一确认当前 CLI 环境的 PHP 路径和版本：
which php
/usr/bin/php
php -v
PHP 8.1.2 (cli) (built: Oct 12 2023 15:23:31) (NTS)
php -i | grep "Loaded Configuration File"
Loaded Configuration File => /etc/php/8.1/cli/php.ini

2.2 补齐 Composer 运行的四大支柱扩展

Composer 的启动和运行，至少依赖以下四个 PHP 扩展。缺一不可，且顺序不能乱——因为某些扩展的加载依赖于其他扩展已就位。

php8.1-cli ：这是基础中的基础。 php-cli 是 PHP 的命令行接口，没有它， php composer.phar install 根本无法执行。Ubuntu 22.04 通常已预装，但需验证：
```
sudo apt update
sudo apt install -y php8.1-cli
```
如果提示 php8.1-cli is already the newest version ，说明已存在；如果提示 Package 'php8.1-cli' has no installation candidate ，说明你的系统可能被修改过源，需检查 /etc/apt/sources.list.d/ 下是否有冲突的第三方源。

php8.1-zip ：这是最常被忽略的致命依赖。Composer 在下载包后，必须用 zip 扩展来解压 .zip 格式的包存档。很多用户报错 failed to unzip ，第一反应是 ZIP 文件损坏，其实 95% 的情况是 php-zip 没装。验证方法很简单：

php -m | grep zip
# 如果无输出，说明未启用
sudo apt install -y php8.1-zip
sudo systemctl restart apache2  # 如果你用 Apache，需重启服务使扩展生效
# 对于纯 CLI 场景，无需重启，但需确认 php.ini 中 extension=zip.so 已取消注释

php8.1-xml ：Composer 的 composer.json 和 composer.lock 文件虽是 JSON 格式，但其内部依赖解析引擎（特别是处理 package.xml 元数据时）会调用 libxml 库。更重要的是，许多 PHP 框架（如 Laravel）的配置文件、测试框架（PHPUnit）的 XML 报告都依赖此扩展。不装它， composer install 可能成功，但后续项目运行会报 Class 'DOMDocument' not found 。
```
sudo apt install -y php8.1-xml
```
php8.1-mbstring ：多字节字符串处理扩展。Composer 在解析包名（尤其是含中文或特殊字符的包名）、生成自动加载文件路径时，必须用 mb_ 系列函数进行安全的字符串截取和编码转换。缺少它， composer create-project 创建新项目时，可能在生成 autoload_static.php 时崩溃。

注意： unzip 命令本身是系统级工具，和 PHP 扩展无关，但它是 Composer 的“备胎”。当 php-zip 扩展不可用时，Composer 会退化使用系统 unzip 命令。所以， sudo apt install unzip 这一步也必须做，它是双保险。实测下来， unzip

最低0.47元/天解锁文章