企业官网建设流程全解析

在Gradle进阶这个系列里，前几篇聊了任务依赖、构建脚本优化和自定义插件，今天把视角转向工程化日常里非常实用的一块：结合Sonarqube做代码审查。简单说，就是通过Gradle的sonarqube插件，在构建流程里自动把源码、编译产物和统计信息推送到Sonarqube服务端，由它跑一遍静态分析，输出Bug、漏洞、坏味道、重复率、覆盖率这些指标。这篇适合正在用Gradle做Java或Android项目、想把代码质量检查从“靠人眼”升级成“自动卡点”的团队和个人开发者。我会把服务端搭建、Gradle配置、参数含义和踩坑经验都过一遍，保证你看完能直接在自己的项目里跑起来。

1. 代码审查这件事，为什么我推荐用Sonarqube

很多团队一说“代码审查”，第一反应是人肉Review。代码走查、小组评审、提交MR后同事点赞评论，这些都是靠人去做的。人有人的优势，看得出业务逻辑合不合理、接口设计有没有问题，但人也有天然的短板——漏检率其实相当高，尤其是那种几千行的老模块，让一个不熟悉上下文的人去挑毛病，效率非常低。机器静态分析在这件事上是特别好的补充，它不会累、不会漏，规则匹配一遍扫过去，能快速把明显的问题挑出来。

1.1 人工走查和机器扫描，谁也不能替谁

有段时间我觉得“都上了Sonarqube了，还要人Review干嘛”，后来被打脸了。真实情况是，Sonarqube这种平台解决的是“代码里有没有违反通用规则的问题”，比如空指针隐患、资源没关闭、明显的线程安全问题、方法复杂度太高、重复代码块。它不关心你的业务逻辑对不对，也不理解这个接口为什么这么设计。

代码走查和代码审查（人做的部分）解决的是另一层问题：这个改动是不是合理的、有没有更优雅的实现、有没有考虑边界情况。所以比较健康的状态是两套并行——人看逻辑，机器查规则。尤其是团队里有新人或者接手历史代码的时候，机器的扫描报告能帮Reviewer快速定位可疑位置，节省大量时间。

1.2 接入Gradle之前的两个关键认知

第一个认知：扫描应该是构建过程的延伸，不是单独跑的独立工具。Sonarqube分析Java项目时，如果能拿到编译后的class文件，分析深度和准确率会高很多，很多规则需要读取字节码信息，纯源码级别分析会损失一部分能力。Gradle恰好能在生命周期里控制这一切，编译完成后、任务结束前就是扫描的最佳窗口。这也是为什么直接在构建工具里集成，比手动跑一个扫描器要优雅得多。

第二个认知：扫描结果本身只是数据，真正约束流程的是质量门禁（Quality Gate）。很多人只把Sonarqube当成“看报告”的工具，跑完任务看两眼页面就结束了，那和随手装个TODOLint差不多。只有配置了门禁——比如“新增代码覆盖率必须达到80%、严重Bug为0”——并且让CI流水线去等待和读取这个结果，才能起到自动拦截的作用。后面第4部分会详细讲这块。

2. 先把服务端跑起来：Sonarqube安装与初始化

Sonarqube分两个角色：服务端和扫描端。服务端负责存数据、跑分析任务、展示报告；扫描端就是我们Gradle里集成的那一部分，负责收集数据上传给服务端。所以安装配置服务端是第一步，先把“家”建好，再谈接入。

2.1 版本选择和Java/PostgreSQL配套

Sonarqube的服务端本身是个Java应用，所以你要先确认机器上的Java版本。这里有个容易踩的坑：不同版本的Sonarqube服务端对JDK要求不一样。9.9 LTS版本跑在Java 11上没问题，后面10.x系列开始要求Java 17。如果你机器上装的是Java 8，那不管是哪个版本都白搭，启动直接报错。

数据存储方面，内置的H2数据库只适合体验用，正式跑哪怕是自己个人的项目，我还是建议用PostgreSQL。Sonarqube对PostgreSQL的兼容性最好，9.x版本支持到12到14左右的版本区间，10.x也有对应的支持范围，用太新的PostgreSQL版本有时候反而会出现驱动不兼容的情况。如果你有现成的PostgreSQL实例，直接建一个名字叫sonar的库，角色权限给够就行。

我自己的选择是：本地开发环境直接用Docker Compose把PostgreSQL和Sonarqube一起拉起来，三分钟搞定，不用在系统里装一堆依赖。下面这个compose文件是我一直在用的模板。

2.2 用Docker Compose一键起服务

services: postgres: image: postgres:13 container_name: sonar-postgres environment: POSTGRES_USER: sonar POSTGRES_PASSWORD: sonar POSTGRES_DB: sonar volumes: - sonar-postgres-data:/var/lib/postgresql/data restart: unless-stopped sonarqube: image: sonarqube:9.9.3-community container_name: sonarqube depends_on: - postgres ports: - "9000:9000" environment: SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonar SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: sonar volumes: - sonar-data:/opt/sonarqube/data - sonar-extensions:/opt/sonarqube/extensions - sonar-logs:/opt/sonarqube/logs restart: unless-stopped volumes: sonar-postgres-data: sonar-data: sonar-extensions: sonar-logs:

把上面内容保存成docker-compose.yml，在同一个目录下执行：

docker compose up -d

第一次启动要等一会儿，Sonarqube初始化数据大概需要一两分钟。你可以通过日志确认启动进度：

docker compose logs -f sonarqube

看到类似SonarQube is up之类的日志之后，浏览器打开http://localhost:9000，默认账号是admin，密码也是admin。登录进去第一件事就是改密码，这个没什么好说的，安全习惯问题，哪怕只是本地跑也顺手改掉。

2.3 创建项目、生成Token，别再用admin账号扫代码

服务端登录之后，首页会引导你创建项目。填入项目显示名称和项目标识（project key），这个project key后面在Gradle里配置时要用到，建议取一个有意义且固定的值，比如my-project这种，后面不会动不动改。

创建完项目，页面会提示你选择分析方式，并给你生成一个Token。这个Token才是Gradle扫描时用来认证的凭证，不是让你拿用户名密码去登录。很多人第一次接触容易搞混，在Gradle配置里把admin/密码写进去，结果新版Sonarqube的Web API对账号密码方式支持得很别扭，经常认证失败，最后排查半天发现换Token一下就通了。

Token生成后记得立刻复制保存，关掉页面就看不到了。如果丢了也没关系，在Administration -> Security -> Users里可以重新生成或者撤销。自己个人项目用全局Token就好，团队项目建议按项目粒度的Token去生成，权限能控制得更细，某个项目Token泄漏也不会连累其他项目。

服务端准备到这里就告一段落了。顺便提一句，如果你的网络是内网环境，扫描端需要能访问到9000端口，记得检查一下防火墙，这个经常被忽略。

3. Gradle这边怎么配：插件引入与参数拆解

服务端就绪之后，回到项目里做集成。Gradle这边需要做两件事：引入Sonarqube插件、配置扫描参数。看起来简单，但里面的参数如果理解不到位，后期排查问题会很痛苦。

3.1 插件选择和引入姿势

在根项目的build.gradle里加一行插件声明：

plugins { id "org.sonarqube" version "4.4.1.3373" }

如果你的项目用了settings.gradle里面的pluginManagement统一管理插件版本，那就把插件版本写在那边，build.gradle里只保留id，效果一样。插件版本跟Gradle版本有对应关系，老插件配新版Gradle可能会出现兼容问题，我目前用的Gradle 8.x配这个4.4.x版本没出过问题。

多模块项目里，插件只需要在根项目声明一次，子模块会共享。但要注意，默认扫描的范围是根项目及其子项目，如果你是某个模块不想被扫描，可以单独在那个模块的配置里设置sonar.skip为true。

还有一个常见的问题场景（后面排查部分细说）：如果你的项目里有Flutter或者RN的混合构建逻辑，它们的Gradle插件用的是命令式apply方式，跟plugins块的生命周期不同，Sonarqube插件和它们混用的时候偶尔会有诡异的顺序问题。遇到这种项目，我建议你先把纯插件声明方式跑通，再逐步把其他插件接回来。

3.2 核心配置项逐个讲透

插件引入之后，需要在build.gradle里配置一个sonar扩展块：

sonar { properties { property "sonar.host.url", "http://localhost:9000" property "sonar.token", System.getenv("SONAR_TOKEN") property "sonar.projectKey", "my-project" property "sonar.projectName", "My Project" property "sonar.projectVersion", "1.0.0" property "sonar.sourceEncoding", "UTF-8" property "sonar.java.binaries", "${buildDir}/classes/java/main" property "sonar.java.libraries", "${buildDir}/libs/*.jar" } }

挨个讲一下这些参数的含义和为什么这么配：

sonar.host.url：服务端地址。本地就是http://localhost:9000，如果服务端装在内网其他机器上，就改成对应的IP或域名。这个参数是最容易被写错的，有人会漏掉/，有人会写成http://localhost:9000/sonarqube，实际上如果你是用根路径部署的，直接域名+端口就行，不需要加路径。

sonar.token：服务端创建的那个Token。我强烈建议不要直接写死在build.gradle里，而是从环境变量读取，比如上面的System.getenv("SONAR_TOKEN")。原因很简单：build.gradle几乎都会提交到Git仓库，Token写进去就等于公开了。谁都能扫描你的项目不说，敏感项目的数据安全也会出问题。

sonar.projectKey：必须和服务端创建项目时填写的project key完全一致，大小写、连字符都不能差。这个值是服务端识别项目的唯一标识，不一致的后果是扫描数据不会归到你创建的那个项目下，或者直接跑到一个自动创建的无效项目里。

sonar.projectName：展示名称，可以跟projectKey不一样，这个是给人看的，写清晰一点就行。

sonar.projectVersion：项目版本号，默认是1.0。建议设置成和构建版本一致，这样在Sonarqube页面上能看出“这个问题是在哪个版本引入的”。

sonar.sourceEncoding：源码编码。这个不配的话，中文注释和字符串可能全部乱码，扫描结果里的规则标签也会乱。统一UTF-8是绝对正确的选择。

sonar.java.binaries：编译产物目录。对于Java项目来说，这个是核心参数之一。如果你没配这个，Sonarqube只能用源码级分析，错过大量基于字节码的规则检查。我在第5部分会展示一个真实的坑，就是路径指错了导致分析结果几乎为空。

sonar.java.libraries：项目依赖的jar包列表，用通配符指定目录即可。如果你是标准Java项目，一般build/libs/*.jar就够了；Android项目这里会麻烦一点，后面单独说。

3.3 参数传递的三种方式和优先级

项目里的配置方式不止上面一种，你在实际项目中可能会遇到三种传参方式，它们各有适用场景：

第一种是脚本里的sonar.properties块，适合写固定值，比如projectKey、sourceEncoding这种不太会变的参数。第二种是命令行参数，在跑任务时用-Dsonar.host.url=http://xxx覆盖，适合临时指向不同的服务端。第三种是gradle.properties里写systemProp.sonar.host.url=http://xxx，适合区分本地和CI环境的场景。

参数优先级从高到低是：命令行参数大于sonar扩展块里的配置，大于gradle.properties里的配置，最后才是默认值。这个顺序平时用不上，但当你在CI里想覆盖本地配置时就很有用了。比如本地默认连测试服务器，CI里用-Dsonar.host.url直接指向正式服务器，脚本不用改，环境变量一传就行。

4. 执行扫描到质量门禁，这才是完整闭环

配置全部就位，接下来就是执行扫描、看报告、设置门禁，把全流程串起来。

4.1 跑一遍完整扫描流程

执行扫描的命令很简单，在项目根目录运行：

./gradlew sonarqube --no-daemon --info

--no-daemon是避免Gradle守护进程在容器环境下残留，本地开发可以不加。--info是为了看详细日志，首次跑的时候建议加上，能看到扫描器上传了什么、有没有警告。

整个流程大概是：Gradle先执行编译，把Java源码编译成class文件，然后Sonarqube插件收集源码、产物、统计信息，打包上传到服务端，服务端执行异步分析，分析完成后结果展示在页面上。项目小的话几十秒就完成，大项目可能要几分钟，如果配置了等待质量门禁，时间会更长一点。

跑完任务之后，去Sonarqube页面上找到你的项目，你会看到类似这样的指标：Bugs数量、Vulnerabilities漏洞数、Code Smells坏味道数、Coverage覆盖率、Duplications重复率，以及最显眼的Quality Gate状态——Passed还是Failed。

这里要说一个我个人的习惯：第一次跑完扫描，先别急着改代码，先花十分钟把报告从头翻一遍，看看你的历史代码里到底藏了哪些问题。很多老项目的扫描结果会非常惨烈，几十个严重问题都有。这时候不要冲动想一次性全修完，重点是先让流程跑起来，然后再慢慢消化存量问题。这个心态很重要，不然很容易被报告吓退。

4.2 质量门禁怎么设置才有意义

默认的门禁规则叫“Sonar way”，包含几条核心条件：新增代码覆盖率不低于80%（如果传了覆盖率的话）、新增严重Bug为0、新增漏洞为0、新增安全热点已复核。这套规则对大多数项目来说是合理的起点。

在Sonarqube服务端的Quality Gates管理页面可以创建新的门禁规则，我的建议是不要拍脑袋设太高的指标。之前碰到一个团队，上来就把覆盖率门槛定在90%，结果CI天天红灯，最后大家干脆不看Sonarqube了，工具直接废掉。门禁的指标要和团队当前的技术债水平匹配，先定一个“比现状好一点”的目标，比如新增覆盖率60%、严重问题0个，跑上一两个迭代，再逐步收紧。

要让Gradle构建真的去等待并读取门禁结果，需要额外传两个参数：

-Dsonar.qualitygate.wait=true -Dsonar.qualitygate.timeout=300

第一个表示构建等门禁结果返回后才结束，第二个是超时时间，单位是秒。如果门禁没过，Gradle任务就会以失败状态退出，CI流水线就能据此拦截本次构建。如果不加这两个参数，Gradle只是把数据传上去就完了，根本不管门禁过没过，那就失去了自动拦截的意义。

4.3 接入CI流水线的推荐姿势

本地开发手动跑扫描只是一个起点，真正让Sonarqube发挥威力的是接入CI。以GitLab CI为例，在一个测试阶段管道里加一个job：

sonarqube: stage: test script: - ./gradlew sonarqube --no-daemon -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN -Dsonar.qualitygate.wait=true -Dsonar.qualitygate.timeout=300 only: - merge_requests - main

这里的$SONAR_HOST_URL和$SONAR_TOKEN是CI里配置的环境变量，Token放在CI的Secret变量里，不会暴露在日志中。only字段建议按团队规范来，核心分支和MR必跑，临时分支可以跳过，不然每个分支都扫描一遍，集群资源会比较吃紧。Jenkins的写法和这个类似，本质都是执行Gradle命令后根据退出码判断是否通过。

接入CI后你会发现，代码审查的节奏变了：以前是提交MR后人肉Review时才发现代码风格有问题，现在是在流水线阶段机器就已经把所有通用问题挑出来了，Reviewer的精力可以集中在真正需要人判断的地方。

5. 实测中高频问题与避坑经验

这个部分是我最想写的。Sonarqube作为Java生态的老牌工具，功能确实强，但坑也不少。下面这些问题，每一个都是我或身边同事真实踩过的，列出来给你省点时间。

5.1 三个高频报错和应对

我在热搜词里看到很多人搜Gradle离线包、国内镜像，其实大多数都是下面这几个问题。直接上表格：

第一个问题最经典。Gradle Wrapper首次运行时会根据gradle/wrapper/gradle-wrapper.properties里的distributionUrl下载Gradle发行包，默认指向官方仓库，网络状况不好的时候特别容易超时。解决办法是把distributionUrl换到国内镜像：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip

腾讯云和阿里的镜像都可以用，具体版本号换成你项目需要的版本就行。换完记得把gradle-8.7-bin.zip后面的哈希校验值（如果有的话）也对应删掉或注释掉，不然校验不过还是会报错。

第二个问题本质是依赖仓库访问不到。在settings.gradle里加镜像仓库：

pluginManagement { repositories { maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } maven { url 'https://maven.aliyun.com/repository/central' } google() gradlePluginPortal() } } dependencyResolutionManagement { repositories { maven { url 'https://maven.aliyun.com/repository/central' } maven { url 'https://maven.aliyun.com/repository/google' } google() mavenCentral() } }

这个配置在Android项目里尤其常见，如果你用Android Studio每次新建项目都卡在配置Gradle，多半就是官方源访问太慢，把镜像源配好能解决99%的问题。

第三个问题比较隐蔽，表面上是“任务执行成功了但服务端没数据”，实际往往是projectKey大小写不对，或者Gradle从某个缓存里读了旧配置。最常见的还是sonar.java.binaries路径不对，导致分析阶段根本没有可用的字节码。下面单独展开。

5.2 扫描结果不全/为空怎么办

我见过最多的情况是：Java项目跑完sonarqube，页面上确实出来了报告，但内容稀稀拉拉，Bug、Code Smell加起来就几个，明显不对劲。这时候优先检查这几项：

第一，看执行日志里有没有“No files matching”或“Unable to resolve”的警告。如果有，说明源码目录或字节码目录没找对。Java项目的源码默认在src/main/java，如果你项目结构特殊，要显式指定sonar.sources。

第二，看sonar.java.binaries是不是指向了真正的class输出目录。标准Java项目编译产物在build/classes/java/main，但如果你用的是自定义构建逻辑或者模块结构比较复杂，这个目录可能不对。我之前接一个老项目，编译产物在build/classes/java/classes下面，当时没细看，扫描结果几乎为空，翻了好多文档才定位到是路径问题。

第三，检查sonar.projectKey是否和服务端完全一致。有人会在服务端创建项目时叫my-project，在Gradle里写my_project，下划线连字符一字之差，扫描任务还是成功，但数据会归到另一个自动创建的“脏”项目里。

第四，如果有中文乱码，检查sonar.sourceEncoding是否为UTF-8。这个问题在Windows环境下尤其常见，默认编码可能是GBK，分析一跑全乱。

5.3 误报处理与规则配置心得

静态分析器产生误报是必然的，Sonarqube也一样。有些代码在特定业务场景下就是合理的，但规则引擎不知道，照样给你标个Blocker级别的问题。处理误报有几种方式，按推荐程度排列：

第一种是局部抑制，在代码行尾加// NOSONAR注释，或者在方法/类上按规则ID标注抑制注解。这种方式适合偶发的、局部的误报。比如某个工具类里的空指针检查，代码逻辑上确实保证了不为空，但静态分析看不出来，就可以用注释说明抑制原因。这里有个讲究：抑制注解必须写理由，不然会和代码一起被质疑。

第二种是全局规则调整，在服务端将某些高噪音规则关闭或降级。比如有的团队觉得魔法数规则太吵，直接在质量配置里把对应规则设为不激活，比在代码里到处加抑制注释干净得多。

第三种是使用sonar.issue.ignore.multicriteria批量忽略特定路径下的特定规则，适合处理生成的代码、自动生成的Mapper或模型类，这些代码没有人工审查价值，扫出来全是噪音。

我的建议是：刚开始用默认的Sonar way就行，别一上来就开一堆自定义规则。跑几个迭代后，观察哪些规则经常误报、哪些规则确实拦住了真实问题，再做针对性调整。工具是给人用的，不是用来折磨人的，过度配置只会让大家反感。

5.4 多模块与Android项目的两个补充提醒

如果你是标准的单模块Java项目，前面说的内容已经够用了。但现实中很多项目是多模块的，甚至带Android模块。多模块情况下，sonar.java.binaries很难用一个路径覆盖所有模块，Sonarqube插件支持为不同模块单独设置属性。你可以在每个子模块的build.gradle里加：

sonar { properties { property "sonar.moduleKey", "${project.group}:${project.name}" property "sonar.java.binaries", "${buildDir}/classes/java/main" } }

Android项目更麻烦一点，因为Android的字节码生成过程跟纯Java不一样。如果用AGP，class文件可能分布在build/intermediates/javac/下，并且要依赖于compile任务执行完成。比较省力的做法是直接在根项目配一个粗略的sources和binaries路径，先跑通再说。Android模块的Sonarqube分析细节可以单独开一篇聊，这里不展开，但你至少要有个预期：Android项目接入比纯Java项目要费更多功夫，耐心排查路径问题是常态。

如果你在Android项目里还遇到Flutter或RN插件混在一起的情况，日志里出现“you are applying flutter's main gradle plugin imperatively using the apply”这类提示，先不用慌，把它当成一个独立的构建逻辑问题处理。重点检查插件声明顺序和apply方式是否冲突，Sonarqube插件本身并不冲突，真正冲突的是不同插件对构建生命周期不同阶段的干预顺序。

5.5 一些零散但非常实用的习惯

最后分享几个我踩过坑之后养成的习惯：

给Gradle配镜像源之后，记得同步到CI环境。本地改好了没用，CI服务器有时候还是走官方源，照样超时。把镜像配置写死到项目里的gradle-wrapper.properties和settings.gradle，提交进仓库，这样不管谁克隆、在哪台机器构建，行为都一致。

Token管理一定走环境变量或CI Secret，绝不写在构建脚本里。之前看到有人在示例代码里用占位Token“squ_xxxx”，结果被搜索引擎收录了，等于给全网开了个扫描端口。Token泄漏的直接后果是任何人都能往你的Sonarqube项目里传数据，垃圾数据多了报告就没法看了。

如果要让Gradle扫描和构建同时跑得快，注意扫描任务会自动触编译，不要在一个流水线里既手动执行build又执行sonarqube任务，后者已经内含编译这个过程，重复构建纯属浪费资源。把sonarqube任务作为流水线的一个独立stage，它自己会处理好依赖关系。

关于服务端性能和容量，如果你团队超过十个人在用Sonarqube，尽量别再跑在个人电脑或者1核2G的小云主机上，扫描任务并发一上来，服务端内存直接吃满，Elasticsearch组件经常因为内存不足自动退出。我的经验是至少4G内存起步，存储IO也别太差，不然任务排队排到天荒地老。

写在最后的个人体会

这套流程从技术上讲并不复杂，难的是让团队接受并坚持使用。我个人的体会是，Sonarqube真正的价值不是找到多少Bug，而是让团队对“代码质量”这件事有了一个可量化的共识。以前Review时有人说“这段代码写得不干净”，很难说清到底脏在哪，现在直接甩一个扫描报告，哪些是Blocker、哪些是Major、为什么是Major，一目了然。刚开始跑的时候，看到存量问题一大堆很容易焦虑，放轻松，先把门禁规则定到一个团队能承受的水平，跑顺了再一点点收紧。这一套东西走通之后，你会发现代码审查不再是一个让人头大的环节，而是有数据、有流程、可持续改进的工程实践。