composer如何配置ssl证书_composer常见SSL连接错误解决方法【总结】

composer ssl 错误主因是 OpenSSL 证书验证失败，常见于系统 CA 过旧、低版本 OpenSSL、php 未链接正确 CA 包或 httpS 代理拦截；应通过更新证书、配置 cafile 或导入完整证书链解决，禁用 secure-http 不推荐。

Composer 默认通过 https 连接 Packagist，若系统 CA 证书过旧、代理拦截、或自建镜像启用私有 SSL 证书，就会触发 SSL 握手失败。最直接的判断依据是报错里含 SSL routine:ssl3_get_record:wrong version number、curlOPT_SSL_VERIFYPEER 或 unable to verify the first certificate —— 这类错误基本不是 Composer 本身的问题，而是 OpenSSL 层面的证书验证失败。

为什么 composer install 突然报 SSL 错误？

常见诱因有三类：系统 OpenSSL 版本太低（如 centos 6 自带 OpenSSL 1.0.1e）、PHP 编译时未链接系统最新 CA 包、或公司网络中间有 HTTPS 解密代理（比如 Zscaler、Netskope）。尤其在 docker 容器或 CI 环境中，基础镜像常精简掉 /etc/ssl/certs/ca-certificates.crt 或未更新证书包。

• 运行 openssl version -a 查看 OpenSSL 编译路径，确认是否加载了系统证书目录
• 执行 php -r "print_r(openssl_get_cert_locations());"，检查 default_cert_file 指向的文件是否存在且可读
• 若使用企业代理，尝试临时关闭代理再运行 composer diagnose，观察是否仍报错

如何让 Composer 信任自签名或内网镜像证书？

不要全局禁用 SSL 验证（即避免 composer config -g secure-http false），而应把证书加入 PHP 的信任链。关键是让 PHP 的 OpenSSL 扩展能读到它。

• 将 PEM 格式证书（如 my-mirror.crt）追加到系统 CA 包：sudo cp my-mirror.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates
• 若 PHP 使用独立证书路径（如 Alpine linux），需显式配置：echo "openssl.cafile=/etc/ssl/certs/ca-certificates.crt" >> /usr/local/etc/php/conf.d/docker-php-ext-openssl.ini
• 验证是否生效：php -r "var_dump(stream_context_create(['ssl' => ['cafile' => '/etc/ssl/certs/ca-certificates.crt']]));" 不报错即表示路径可读

curl_setopt(): CURLOPT_SSL_VERIFYPEER 错误怎么修？

这个警告实际来自 Composer 底层调用 cURL 时的参数冲突，常见于 PHP 8.0+ 和旧版 cURL 组合，或某些 windows XAMPP 环境默认关闭了证书验证但又没配好路径。

composer config -g cafile /etc/ssl/certs/ca-certificates.crt

这行命令会写入全局配置 ~/.composer/config.json 的 cafile 字段，强制 Composer 使用指定证书文件，绕过 PHP 自动探测逻辑。注意路径必须是绝对路径，且文件需存在、权限为 644。

• Windows 用户请用正斜杠或双反斜杠：composer config -g cafile C:/xampp/htdocs/certs/root.crt
• 若仍报错，检查是否被 http_proxy 环境变量干扰 —— 某些代理会篡改 TLS SNI，此时需设置 no_proxy="packagist.org,repo.packagist.com"
• Docker 构建中建议在 Dockerfile 末尾加 RUN composer config -g cafile /etc/ssl/certs/ca-certificates.crt，避免每次构建都重配

真正麻烦的不是加证书，而是证书链不完整 —— 比如只提供了站点证书，没附带中间 CA。用 openssl s_client -connect repo.my-company.com:443 -showcerts 能看到完整链，复制全部 PEM 块（包括 -----BEGIN CERTIFICATE----- 到 -----END CERTIFICATE-----）合并成一个文件再导入，才真正有效。