写代码的人大概都经历过这种事项目上线前看着代码没啥问题一上线就出幺蛾子。后来团队引入静态代码分析把检查环节卡在提交之前情况才算好转。我在 Windows 环境下从零搭过 SonarQube 和 Sonar Scanner 的组合踩了不少坑把整个搭建配置过程整理出来给打算在自己电脑上或公司内网搭一套代码质量分析平台的同学做个参考。这篇东西适合后端开发者、测试工程师、运维同学也适合想给团队建立代码质量门禁但没有专门服务器资源的小团队。1. 环境准备版本搭配与Windows下的几个坑1.1 版本选型是最容易被忽略的起跑线第一次搭建的人往往一上来就下载最新版 SonarQube然后卡在启动环节。SonarQube 对 JDK 版本有硬性要求比如 9.x 系列要求 JDK 1710.x 系列要求 JDK 17 或 21而早年用的 7.x 系列只要 JDK 8。版本不对服务直接起不来错误日志里会明确提示缺失 Java 11/17 之类。我建议直接用目前还在维护的 LTS 版本比如 SonarQube 9.9 LTS 配 JDK 17这是比较省心的组合。数据库方面默认自带 H2 只适合试用一重启数据就没了真正要用必须换 PostgreSQL。9.9 对 PostgreSQL 的兼容范围是 13 到 15我实测 14 和 15 都没问题。这里有一个基础版本搭配表可以直接照着准备组件推荐版本说明SonarQube9.9 LTS 或 10.xLTS 优先稳定且资料多JDK1764位9.9 必须 1710.x 要求 17PostgreSQL14 或 159.9 兼容 13~15别用 16Sonar Scanner与 Server 同版本或更高版本差异过大可能认证失败1.2 Windows下JDK配置要注意的细节Windows 上装 JDK 有两个坑一是环境变量配错二是装了多个 JDK 导致版本混乱。SonarQube 启动时读的是 JAVA_HOME不是 PATH 里的 java所以务必在系统变量里设置JAVA_HOME指向 JDK 安装目录然后在 PATH 最前面加上%JAVA_HOME%\bin。设置完在命令提示符里跑java -version确认版本注意别看到 1.8 就觉得完事了。另一个细节是位数。SonarQube 服务端是 Java 应用跑在 64 位 JDK 下内存管理更从容。如果你机器上装了 32 位 JDK后面调大内存参数时经常会报Could not reserve enough space for object heap排查半天才发现是 JDK 位数不对。所以统一用 64 位 JDK 17不要混用。1.3 PostgreSQL 准备用户、密码和数据库一步到位数据库这一步很多人直接跳过觉得默认 H2 够了等第二次启动发现之前配置的分析记录全没了才后悔。PostgreSQL 装好后用 pgAdmin 或者命令行创建 SonarQube 专用的用户和数据库不要用 postgres 超级用户去跑原则是权限最小化。我用命令行演示一次Windows 下直接打开 psql 工具执行CREATE USER sonar_user WITH ENCRYPTED PASSWORD sonar_pass; CREATE DATABASE sonar_db OWNER sonar_user; GRANT ALL PRIVILEGES ON DATABASE sonar_db TO sonar_user;记住这个库名和账号密码后面配置 sonar.properties 要原样填进去。PostgreSQL 安装完默认监听 5432 端口如果改过端口后面配置里也要对得上。还要检查 PostgreSQL 的pg_hba.conf确认本地连接方式是md5或scram-sha-256否则 SonarQube 连接时会弹认证失败。1.4 路径、防火墙和“不要用管理员”三条规矩Windows 下安装路径一定不要带中文、空格和特殊符号比如把 SonarQube 解压到D:\Program Files这种路径就会莫名奇妙出问题。我习惯建一个干净的目录比如D:\sonar\sonarqube-9.9和D:\sonar\sonar-scanner。防火墙方面SonarQube 默认监听 9000 端口如果你要局域网内其他同事访问需要在 Windows 防火墙入站规则里放行 TCP 9000。自己在本机调试则不用管。最后一条启动 SonarQube 时不要右键“以管理员身份运行” StartSonar.bat因为管理员模式下关闭命令窗口不会让 Java 进程退出而是直接杀掉服务反而更容易出现端口未释放的问题。普通用户双击启动脚本就行。2. SonarQube 服务端安装从解压到首次初始化2.1 下载和解压的正确姿势SonarQube 的发行包是 zip 格式解压后目录结构大概是bin、conf、lib、logs、extensions这几个。第一次拿到包时不要急着启动先把conf\sonar.properties打开把数据库和端口配置改好。这里有个经验解压之后先看一眼logs目录是不是空的如果里面有报错日志说明之前有人启动过最好重新解压一遍避免残留配置干扰排错。我遇到过解压过程中被杀毒软件拦截部分文件的情况结果启动时缺 class 文件直接崩溃。Windows Defender 偶尔会误杀启动脚本或 jar建议把 Sonar 目录加入信任区。2.2 sonar.properties 里的核心配置项打开conf\sonar.properties大部分内容都是注释状态把需要的那几行取消注释并改成自己的值。关键配置如下sonar.jdbc.usernamesonar_user sonar.jdbc.passwordsonar_pass sonar.jdbc.urljdbc:postgresql://localhost:5432/sonar_db sonar.web.port9000 sonar.web.javaOpts-Xmx2048m -Xms1024msonar.web.port默认就是 9000如果 9000 被占用可以改成 9001但记住后面访问地址和 Sonar Scanner 里都要跟着改。sonar.web.javaOpts是 Web 进程的堆内存参数机器内存 8G 的话给 2G 起步太小了跑大项目分析时容易卡死。还有一个参数sonar.path.data决定数据文件存放位置默认在安装目录下。Windows 下我建议把它指到一个独立目录比如D:\sonar\data这样以后升级 SonarQube 时可以直接保留数据目录不用整体拷贝。2.3 启动脚本与“本机访问不了”问题启动方式很简单进入bin\windows-x86-64目录双击StartSonar.bat。这里要注意如果操作系统是 64 位目录一定是windows-x86-64如果装成 x86 版本启动脚本在bin\windows-x86下两者不要搞混否则日志里会一直报找不到平台动态库。启动后不要立刻打开浏览器SonarQube 首次启动要做数据库初始化和数据迁移这个阶段要等 1 到 3 分钟。判断标准是看命令行窗口出现了类似SonarQube up的提示这时再访问http://localhost:9000。如果页面打不开优先看logs\sonar.log和logs\web.log。在这个环节最容易犯的错误是启动后本机能访问但局域网其他电脑访问不了。先检查防火墙是不是放行了 9000 端口再确认sonar.properties里没有把sonar.web.host设置成127.0.0.1。如果确实设置了改成0.0.0.0或干脆注释掉让服务监听所有网卡。2.4 首次初始化登录、改密码、建 Token浏览器访问http://localhost:9000默认账号是admin默认密码也是admin首次登录系统会强制你修改密码。改完之后进入用户菜单在“My Account”里找到 Security 选项卡生成一个 Token。这个 Token 就是后面 Sonar Scanner 连接服务端的凭证。Token 只显示一次一定要复制保存。当年我搭完环境顺手关了页面之后配 Sonar Scanner 的时候回来再取结果又生成了一次弄得口令管理乱七八糟。服务端首次联网会下载一些插件比如语言分析插件、SCM 统计插件国内网络环境下偶尔会超时。不影响核心功能后面配置扫描器时再手动补充离线插件就行。我建议同时安装一个中文语言包插件在 Administration 的 Marketplace 里搜索 Chinese Pack装完重启服务端就是中文界面了排查问题方便很多。3. Sonar Scanner 客户端选型与环境配置3.1 用哪种方式跑分析SonarQube 的客户端不止一种最基础的是 Sonar Scanner CLI适合本地手动跑、脚本定时跑Maven 项目用mvn sonar:sonar插件Gradle 项目用sonarqube插件IDE 里也有 SonarLint 插件。团队刚起步时建议统一用 Sonar Scanner CLI它不依赖构建工具任何语言都能分析后续接 CI 流程也方便。我个人的实践是开发者在本地用 SonarLint 做编码时实时提示真正做质量门禁和统计时用 Sonar Scanner CLI 去分析。两者使用的是同一套规则库但一个负责边写边查一个负责提交前全量扫描。3.2 下载、解压与环境变量Sonar Scanner 的 zip 包解压后目录里有个bin\sonar-scanner.batWindows 下把SONAR_SCANNER_HOME指向解压目录然后在 PATH 里追加%SONAR_SCANNER_HOME%\bin。配置完成后在新的命令行窗口执行sonar-scanner -v能看到版本信息就说明设置成功。这里有个干扰项如果你同时装了 Jenkins 或 MavenPATH 里可能有其他同名命令。我建议在执行分析的命令行窗口里先用echo %SONAR_SCANNER_HOME%确认指向是否正确避免莫名其妙的“命令未找到”。另外Sonar Scanner 的conf\sonar-scanner.properties里默认写了一个sonar.host.url示例值为http://localhost:9000保持这个值就行也可以在里面预先写好 Token。但我更推荐把 Token 放到项目级的sonar-project.properties里因为 Scanner 的全局配置是全机器共享的写死 Token 容易被误传。3.3 sonar-project.properties 是分析行为的核心执行sonar-scanner命令时它会读取项目根目录下的sonar-project.properties文件。这个文件告诉 Scanner 要分析哪些代码、代码用什么语言、编译产物在哪、哪些文件要排除。我的一个典型配置长这样sonar.projectKeymy-project-key sonar.projectName我的项目 sonar.projectVersion1.0 sonar.sourcessrc sonar.java.binariestarget/classes sonar.sourceEncodingUTF-8 sonar.exclusions**/*DTO.java,**/generated/**sonar.projectKey是项目的唯一标识多个项目不能重复我习惯用公司名加项目名的形式比如order-service。sonar.sources指定源码目录Java 项目必填sonar.java.binaries否则 Java 分析器拿不到 class 文件很多语义级规则跑不起来。sonar.exclusions用来排除自动生成的代码比如 DTO、接口文档生成类避免误报刷屏。如果项目源码在子目录比如 Maven 多模块项目sonar.sources可以写module1/src,module2/src这种逗号分隔形式。模块多的话可以直接在根目录配置后命令进入某个子模块再执行Scanner 会自动识别当前目录。3.4 执行扫描看到 SUCCESS 才算开始配置完整后在项目根目录打开命令行执行sonar-scanner第一次跑会下载对应的分析器插件等个十几秒到几分钟然后开始逐文件分析。日志末尾出现ANALYSIS SUCCESS说明分析完成看到BUILD SUCCESS更完整此时可以去 Web 界面查看报告。如果日志里出现Project does not exist. Please create it first这样的提示代表服务端还没这个项目直接在 9000 端口页面上手动新建项目即可或者手动传sonar.projectKey去匹配已有项目。实际上新版 Scanner 会自动创建项目但如果服务端禁止自动创建项目就需要先手动建。日志中有一段INFO: ANALYSIS SUCCESS, Time:这样的输出这个是 Scanner 自己打印的表示本地处理完成。真正的服务端入库成功要看几秒后的EXECUTION SUCCESS。4. 拿真实项目跑通一次完整分析4.1 准备一个简单的 Java 项目我建议第一次练习时建一个最小的 Maven Java 项目目录结构如下D:\demo-project\ pom.xml src\main\java\com\demo\DemoApplication.java src\main\java\com\demo\OrderService.javapom.xml 里不用加 Sonar 插件因为我们要用命令行 Scanner 独立分析。先在项目目录下执行mvn clean package确保target\classes里有编译产物因为sonar.java.binaries指向这里。代码里故意留点问题——比如一个空的异常捕获、一个可以提升为局部变量的类字段、一个简单的 SQL 拼接——这样分析结果里才能看到不同类型的问题便于熟悉页面。4.2 命令执行与日志解读在项目根目录放好sonar-project.properties然后执行sonar-scanner日志里有一个关键阶段Sensor JavaXmlSensor和Sensor JavaSecuritySensor看到这些说明 Java 分析插件已经加载。完成后继续执行sonar-scanner -Dsonar.projectKeydemo-project -Dsonar.sourcessrc -Dsonar.java.binariestarget/classes -Dsonar.sourceEncodingUTF-8这条命令等价于把配置文件里的参数用命令行方式传入方便临时覆盖配置。如果是首次运行控制台还会输出你的默认 Token 有没有配置没配置的话会提示 401 错误这时去conf\sonar-scanner.properties里补上sonar.token即可。运行完看日志末尾几行INFO: ANALYSIS SUCCESS, Time: 15s INFO: EXECUTION SUCCESS4.3 Web 界面里看什么回到http://localhost:9000左侧会出现demo-project。点进去能看到四个维度可靠性Bugs、安全性Vulnerabilities、可维护性Code Smells和覆盖率Coverage。新建项目的话覆盖率为空是正常的因为还没有关联覆盖率报告。质量门禁Quality Gate显示绿色 Passed 或红色 Failed默认的门禁规则只有几条比如新增代码覆盖率不低于 80%、没有新增 Bug 等。这个门禁可以在 Administration 的 Quality Gates 里自定义。我在团队里就是卡新增代码覆盖率 80% 和新增问题为零这两条太宽松没意义太严格又会阻碍交付。重点还是得结合团队现状慢慢调。初次分析完点进OrderService.java文件能看到每一行代码对应的 warning、note 或 error。左侧筛选器可按类型和严重程度过滤建议先把 Blocker 和 Critical 级别的处理完Minor 的积攒到一定量再统一清。4.4 增量分析与全量分析的差别SonarQube 默认只对新代码的质量门禁负责历史遗留问题只做记录。在后台任务里可以触发“全部重分析”把整个项目重新过一遍。Windows 局域网环境里如果项目很大全量分析时间比较长建议放到夜间定时跑。我在单位就是用 Windows 计划任务定时执行sonar-scanner每天凌晨分析一次主项目早上看一眼质量门禁趋势。这个方案比 Jenkins 轻量适合还没有专门 CI 服务器的小团队。5. 常见问题排查从日志到解决方案的完整链路5.1 启动失败先看 logs 目录别看浏览器SonarQube 服务端启动失败时浏览器会一直转圈或者直接拒连这时候打开logs目录下的sonar.log里面写了完整的启动链路。最典型的错误是数据库连接失败日志里会出现Caused by: org.postgresql.util.PSQLException: FATAL: password authentication failed for user sonar_user这个基本就是sonar.properties里的用户名密码错了。还有一种情况是权限失败日志里提示Access denied for user这是 PostgreSQL 端的问题回头检查pg_hba.conf。所有数据库问题有个共性——日志会明确告诉你哪个环节失败不要一上来就重装。5.2 9000 端口被占用本机同时装了 Jenkins、Nginx 或者其他 Web 服务时SonarQube 默认的 9000 端口很容易撞车。日志里会看到BindException: Address already in use: bind解决办法有两个要么修改 SonarQube 的sonar.web.port要么把占用端口的进程关掉。在 Windows 下查占用进程用netstat -ano | findstr 9000 taskkill /PID 你的进程号 /F我不建议直接 kill因为可能杀掉另一个重要服务。改端口更稳妥但注意同时要改 Sonar Scanner 的sonar.host.url。5.3 JDK 版本不匹配的报错如果日志里出现Unsupported class file major version 61.0说明当前 JDK 版本太老SonarQube 9.9 要求的是 JDK 17class file major version 61 对应 JDK 17。如果出现这个错误去检查JAVA_HOME是不是被旧版本占了或者系统 PATH 里第一个 Java 是 8。顺带提醒执行java -version看到的是 PATH 里的版本和 JAVA_HOME 可能不一致排查时两个都要确认。5.4 分析完成但页面看不到任何问题这种情况最气人——日志显示 SUCCESS页面也出现了项目卡但问题列表是空的。我遇到过两次原因分别是sonar.java.binaries指向的目录不存在以及sonar.sources写成了绝对路径但项目文件在相对路径下认不到。建议检查三件事配置文件里sonar.sources是否写对了相对路径sonar.java.binaries是否指向编译输出目录以及sonar.exclusions是否过滤掉了所有问题文件。还有一个隐藏原因Windows 下编码问题项目源码是 GBK 而sonar.sourceEncoding写了 UTF-8导致中文注释乱码且部分规则无法匹配问题数看着少了一大截。统一改 UTF-8 并从配置里指定编码后问题列表就正常了。5.5 调整 Java 进程内存避免崩溃默认的 JVM 内存配置比较保守分析大型项目时 Web 端或后台任务可能直接崩溃。日志里出现OutOfMemoryError时打开conf\wrapper.conf找到wrapper.java.additional相关配置把最大堆内存调大wrapper.java.additional-Xms1024m wrapper.java.additional-Xmx2048m同时也把sonar.web.javaOpts里的-Xmx调成一致。Windows 32 位 JDK 到 1.5G 堆内存就撑不住了所以还是那句话用 64 位 JDK 是省心前提。6. 最后的实战体会与一个小技巧搭完这一整套环境后最大的体会是SonarQube 的安装本身不难难的是在团队里把流程跑起来。工具放在那没人用等于零要让开发者觉得“它是帮我提前发现问题”而不是“又多了一个被卡的流程”。我现在的做法是每个项目在合并请求前强制跑一次 Sonar Scanner质量门禁没过不让合入连续跑两个迭代后线上缺陷率确实有明显下降。最后分享一个小技巧Windows 下把分析命令封装成一个 bat 脚本放到项目根目录旁边比如scan.bat内容就两行echo off cd /d %~dp0 sonar-scanner以后双击就完成分析。如果想做每日自动扫描就把这个 bat 注册到 Windows 计划任务里触发器选每天凌晨两点起始目录填项目路径稳稳当当。这个方案虽然比不上一键部署的 CI 流水线但对于没地理条件的本地或小团队来说已经足够轻量实用。等以后规模大了再迁移到专门的 CI 上数据和规则都还在迁移成本也不高。