composer在wsl下可用但需三者对齐:php环境(含php-cli、zip、curl等扩展)、文件系统路径(项目须置于wsl原生路径如~/projects/,禁用/mnt/c/)、网络配置(全局配置阿里云镜像源)。

composer 在 WSL 下完全可用,但不是“装上就能跑”,关键在于 PHP 环境、文件系统路径和网络配置三者对齐。装错位置、用错路径、没切镜像,都会导致命令报错、安装卡死或符号链接失败。
确认 PHP 和必需扩展已就绪
WSL 默认不带 PHP,composer 本质是 PHP 脚本,没有 php-cli 就根本启动不了。常见错误如 command not found: php 或运行 composer install 时提示 zip extension is missing,都是因为依赖没装全。
- 运行
php -v,若报错,先执行:sudo apt update && sudo apt install php-cli php-zip php-mbstring php-curl php-xml unzip
- 不要只装
php包(它可能不含 CLI 模块);php-cli是必须项 -
php-zip和php-curl是硬性依赖,缺一不可;php-mbstring和php-xml是绝大多数现代 PHP 项目(如 Laravel、Symfony)所需 - 验证扩展是否加载:
php -m | grep -E 'zip|curl|mbstring',每项都应有输出
全局安装 composer 并确保 PATH 生效
把composer.phar 放进 /usr/local/bin/composer 是最稳妥的方式,但很多人卡在“明明 mv 了却还是 command not found”。
- 正确安装流程:
curl -sS <a href="https://www.php.cn/link/e910517884e11c8a741c3b1da823f47e">https://www.php.cn/link/e910517884e11c8a741c3b1da823f47e</a> | php<br>sudo mv composer.phar /usr/local/bin/composer
- 检查
/usr/local/bin是否在$PATH中:echo $PATH,若无,追加到 shell 配置文件:echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
- 别用
sudo composer日常操作:这会导致vendor/目录属主变成 root,后续git pull或composer update易权限拒绝 - 若仍报错,直接测试:
/usr/local/bin/composer --version—— 成功说明是 PATH 问题,不是安装失败
必须配置国内镜像源,否则大概率超时
默认访问packagist.org 在国内多数 WSL 环境下会卡在 “Loading composer repositories with package information” 十几秒甚至几分钟,最终报 Connection timed out 或 file_get_contents(): SSL operation failed。
- 立即执行(全局生效):
composer config -g repo.packagist composer <a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a> - 验证是否写入:
composer config -g repo.packagist应返回镜像地址 - 不要用
<a href="https://www.php.cn/link/dc02ae8025eef0ecde61b00bb780abdb">https://www.php.cn/link/dc02ae8025eef0ecde61b00bb780abdb</a>(该源已于 2025 年底停止同步),阿里云镜像是当前最稳定选择 - 若项目需临时切回官方源:
composer config -g --unset repos.packagist
避开 Windows 文件系统(/mnt/c/)运行 composer
这是性能和兼容性最大的隐形陷阱。在/mnt/c/Users/xxx/project 下执行 composer create-project 或 require,看似能跑,实则:
- 速度极慢(WSL 访问 NTFS 是跨子系统 I/O)
- 符号链接失败(symlink(): Operation not permitted)
- vendor/ 权限混乱,autoload.php 找不到类
- 正确做法:把项目放在 WSL 原生路径,例如
~/projects/myapp - 若必须从 Windows 编辑代码,用 VS Code 的
code .连接 WSL,编辑器走 Windows,终端和composer全在 Linux 层 - 绝对不要在
/mnt/c/下执行composer install --prefer-source或启用symlinks的插件
真正容易被忽略的,是 WSL 文件系统与 Windows 权限模型的底层冲突——它不会立刻报错,而是在你反复 composer update 失败、vendor 权限变乱、CI 构建突然挂掉时才暴露出来。










