GitLab配置PHP项目coverage徽章始终显示unknown如何解决

核心问题排查按优先级排序： #

1. 修正覆盖率匹配正则 #

你当前.gitlab-ci.yml中配置的正则存在两个错误，直接导致匹配失败：

• 正则中.是通配符，匹配小数点必须转义为\.
• 不同版本PHPUnit输出的覆盖率行前可能存在不可见格式字符，加^行首锚定很容易匹配不到内容

将job中的coverage配置修改为：

php_unit:
  # 其他原有配置保持不变
  script:
    - phpdbg -qrr vendor/bin/phpunit --coverage-text --colors=never --coverage-filter src/
  coverage: '/Lines:\s*\d+\.\d+\%/'

注意：GitLab 13.0及以上版本，job内的coverage字段优先级高于全局配置，不需要在「Settings > CI/CD > General Pipelines」中单独配置全局覆盖率正则，之前配置的全局正则直接清空即可，规则冲突会直接导致提取失败。

2. 确认PHPUnit实际输出了覆盖率内容 #

正则匹配不到内容的最常见原因，是phpunit根本没有打印覆盖率统计：

1. 先在本地或容器内手动执行测试命令，确认输出中存在Lines: XX.XX%格式的统计行
2. 如果没有输出覆盖率，依次排查：
   • 执行phpdbg -qrr -m确认当前环境已加载pcov或Xdebug扩展，没有覆盖率驱动的话phpunit不会生成统计
   • 确认phpunit.xml/phpunit.xml.dist中配置了正确的源码目录白名单，没有白名单时phpunit默认不统计覆盖率
   • 命令后追加--coverage-filter 你的源码目录参数（通常是src/），强制指定统计范围，避免因为配置问题不输出覆盖率
   • 不要在脚本中将phpunit输出重定向到文件，必须让日志直接打印在控制台，否则GitLab无法抓取内容

3. 检查徽章与流水线配置的坑 #

• 覆盖率徽章默认只会拉取项目默认分支最新成功流水线的覆盖率值，如果你在非默认分支修改了配置，必须合并到默认分支并跑完一次成功的流水线，徽章才会更新
• 徽章地址不要硬编码分支名，使用内置变量拼接即可：/%{project_path}/-/badges/%{default_branch}/coverage.svg
• 确认php_unit任务在默认分支的流水线中是正常执行成功的状态，任务被跳过、执行失败、仅在MR流水线中运行时，都不会生成项目级的覆盖率记录

4. 验证提取结果 #

修改配置后触发一次新的流水线，进入php_unit任务的详情页，如果日志右上角能看到Coverage: XX%的标识，说明GitLab已经成功提取到覆盖率值，等待1-2分钟缓存过期后徽章就会正常显示；如果任务详情页没有这个标识，说明正则仍然匹配失败，直接复制日志里的覆盖率行，本地调试正则即可。

其他偶发问题 #

• 自建GitLab实例14.x早期版本存在覆盖率提取后徽章不刷新的已知bug，升级到对应分支的最新小版本即可解决
• 如果配置了流水线制品上传，不要把覆盖率文本日志作为制品上传导致控制台输出被截断，会影响正则匹配

内容的提问来源于stack exchange，提问作者Lioo