Bitbucket Cloud拉取请求页代码质量区SonarQube PR装饰不显示报错

创建Pull Request后流水线执行成功、SonarQube端可查看代码分析结果，但Bitbucket Cloud PR页代码质量模块无法展示PR装饰，核心原因是当前Sonar扫描配置缺失PR装饰必需的上下文参数，SonarQube无法将扫描结果和对应PR关联，无法回写装饰信息到Bitbucket。
对应报错场景如下：

你当前使用的bitbucket-pipelines.yml配置仅配置了基础扫描参数，未针对PR场景传入专属配置项，且缺少主干分支扫描逻辑，而PR增量装饰必须依赖主干分支的基准扫描结果才能正常渲染。
另外需要先确认前置基础配置是否满足要求：

• SonarQube版本为Developer Edition及以上（社区版不提供PR装饰能力）
• SonarQube服务端已完成Bitbucket Cloud集成配置，填入了正确的Workspace信息，授权的OAuth凭证拥有PR读写权限
• SonarQube对应项目已正确绑定目标Bitbucket Cloud仓库

1. 修改流水线配置，自动适配分支/PR扫描场景 #

Bitbucket Pipelines在PR触发时会自动注入PR编号、源分支、目标分支等内置环境变量，无需硬编码参数，调整配置文件内容如下：

image: maven:3-openjdk-11

definitions:
steps:
- step: &build-step
    name: SonarQube analysis
    caches:
      - maven
      - sonar
    script:
      - |
        if [ -n "$BITBUCKET_PR_ID" ]; then
          # PR触发时传入装饰所需的PR上下文参数
          mvn verify sonar:sonar \
            -Dsonar.projectKey=java_base_project \
            -Dsonar.pullrequest.key=$BITBUCKET_PR_ID \
            -Dsonar.pullrequest.branch=$BITBUCKET_BRANCH \
            -Dsonar.pullrequest.base=$BITBUCKET_PR_DESTINATION_BRANCH
        else
          # 普通分支/主干推送时走常规全量扫描
          mvn verify sonar:sonar -Dsonar.projectKey=java_base_project
        fi
caches:
  sonar: ~/.sonar

clone:
depth: full

pipelines:
branches:
  feature/sonarqube_integration:
    - step: *build-step
  feature/sonarqube_integration_2:
    - step: *build-step
  feature/sonarqube_integration_3:
    - step: *build-step
  # 新增主干分支扫描配置，PR装饰需要主干扫描结果作为对比基准，请替换为你实际的主干分支名
  '{main,master}':
    - step: *build-step

pull-requests:
  '**':
    - step: *build-step

2. 配置生效前的校验项 #

提交配置修改、重新触发PR流水线前，确认以下配置无误：

• SonarQube项目配置中，sonar.pullrequest.provider参数已设置为Bitbucket Cloud
• SonarQube绑定的Bitbucket Cloud应用已开通pullrequests:write权限，无该权限时扫描成功也无法回写装饰内容到PR页面
• 主干分支已完成至少一次全量Sonar扫描，PR装饰会基于主干结果对比识别增量代码问题

3. 问题排查快捷路径 #

如果调整配置后PR装饰仍无法正常展示，直接登录SonarQube服务端，进入对应项目的后台任务页面，找到PR对应的扫描任务查看执行日志，日志会明确标注PR装饰失败的具体原因（如权限不足、参数缺失、目标分支不存在等），无需在Bitbucket侧盲目排查。

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