CircleCI构建PHP项目失败主因是环境配置或缓存策略问题：composer install慢因缺失composer.lock或未启用缓存；phpunit失败多因autoload-dev未生效、路径不匹配或PHP扩展缺失；translation校验需全路径、禁用gitignore并区分lint:xliff与translation:lint。
CircleCI 构建 PHP 项目失败，大概率不是代码问题，而是环境配置或缓存策略没对上——尤其在 composer install 和 phpunit 这两步卡住时，90% 是镜像、缓存或权限惹的祸。
为什么 composer install 在 CircleCI 上慢得像挂了？
默认用 circleci/php:7.4-node-browsers 这类镜像，虽然开箱即用，但自带的 Composer 缓存机制常被忽略。更关键的是：没有 composer.lock 文件，或本地和 CI 的 PHP 版本不一致，会导致依赖解析重算，耗时飙升。
- 必须确保项目根目录存在
composer.lock，且提交到 Git（不要忽略它） - 在
.circleci/config.yml中显式启用缓存，别只靠restore_cache：steps: - restore_cache: keys: - composer-v1-{{ checksum "composer.lock" }} - run: composer install --no-interaction --prefer-dist - save_cache: paths: - vendor key: composer-v1-{{ checksum "composer.lock" }} - 避免用
php:8.2-cli这类官方镜像直接跑构建——它没预装git、zip等 Composer 依赖工具，会默默失败或降级为慢速安装
phpunit 找不到测试文件或报错 Class not found？
不是测试代码写错了，是 autoload-dev 没生效，或者 phpunit.xml 路径配置和 CircleCI 工作目录不匹配。CircleCI 默认工作目录是 ~/project，但很多项目假设在 ./ 下运行。
- 在
run步骤中加pwd和ls -la tests/，确认测试目录真实存在 - 显式指定
phpunit配置路径，比如：vendor/bin/phpunit --configuration phpunit.xml.dist - 如果用 Symfony，注意
bin/phpunit可能依赖APP_ENV=test，需在run前设置：APP_ENV=test vendor/bin/phpunit - PHP 扩展缺失（如
mbstring、xml）也会导致 PHPUnit 启动失败，可在run前加检查：php -m | grep -E "(mbstring|xml|pdo)"
如何让 translation:lint 或 lint:yaml 真正起效？
Symfony 的翻译校验命令（如 php bin/console translation:lint）在 CI 里常被当成“可选步骤”，但它其实能提前暴露多语言项目中最隐蔽的错误：键名拼错、XLIFF 格式错位、占位符不匹配。一旦漏掉，上线后用户看到的是空字符串或异常。
立即学习“PHP免费学习笔记（深入）”；
- 必须把
translations/目录路径写全，且确保它被checkout拉下来（有些项目把它 gitignore 了） - 加
--format=json并输出到文件，方便后续解析或归档：php bin/console translation:lint --format=json translations/ > lint-result.json - 若用 XLIFF，别只跑
translation:lint，还要补一句：php bin/console lint:xliff translations/—— 它专查 XML 结构合法性，translation:lint不覆盖这点 - 注意命令退出码：这些 lint 命令发现错误时返回非 0，CI 会自动中断流程，这是好事，别用
|| true掩盖
最易被忽略的一点：CircleCI 的 Docker 执行器默认不共享进程命名空间，所以 php-fpm 或 symfony server:start 这类后台服务无法在 CI 中真正“跑起来”做集成测试——别白费力气配它们，专注单元测试 + 静态分析 + 文件格式校验，这才是 PHP CI 的合理边界。
