企业官网建设流程全解析

简介：SonarScanner 4.2.0.1873 是 SonarQube 生态中用于代码质量与安全扫描的命令行工具，面向需要在 Windows 平台落地静态代码分析的开发、测试与 DevOps 人员。它可深度识别代码复杂性、重复度、潜在缺陷、代码异味及安全漏洞，并支持 Java、C#、Python 等多语言项目，适合集成到持续集成流程中。压缩包共 327 个文件，约 37.77MB，以 79 个 dll 动态库、16 个 exe 可执行文件、6 个 properties 配置、2 个 bat 批处理脚本及 2 个 jar 包为主，另含 jre 运行环境、lib 依赖库与 conf 配置目录，开箱即可在 Windows 上运行，无需额外安装 Java。已有 298 人学习下载。通过 bin 下的 sonar-scanner.bat 配合 conf 中的 sonar-scanner.properties，可快速配置项目路径、服务器地址与认证信息，生成详细代码质量报告，帮助团队定位技术债务、指导重构优化，是跨平台多语言项目持续改进代码质量的实用工具包。

1. 解压即用的 sonar-scanner：Windows 上把代码质量门禁跑起来

很多团队在 CI 上跑 SonarQube 分析很顺，一到本地 Windows 开发机就卡住：要么装完不知道sonar-scanner命令为什么找不到，要么扫出来的报告和服务器上对不上。sonar-scanner-4.2.0.1873-windows.zip这个包解决的正是这件事——它是 SonarScanner 的 Windows 免安装发行版，解压后配好conf/sonar-scanner.properties和PATH，就能在命令行里对任意项目发起一次扫描，把结果推到 SonarQube 服务端。它适合三类人：需要在提交前自查的开发者、要给 Windows 构建机接质量门禁的运维、以及想在没有管理员权限的机器上临时跑一次分析的测试同学。这一章先把「它是什么、为什么用这个版本、跑通的最小路径」讲清楚，后面几章再拆参数、排错和进阶玩法。

SonarScanner 本质是一个 Java 写的命令行客户端，它不负责分析规则，只负责收集源码、调用分析引擎、把结果打包发给 SonarQube。所以它有两个硬依赖：一是本机要有 Java 运行时（4.2 这个版本对 JDK 8 和 11 都友好），二是要有一个可达的 SonarQube 服务端地址和 token。Windows 版 zip 里已经带了启动脚本bin/sonar-scanner.bat，省去了自己拼 classpath 的麻烦。很多人第一次翻车不是配置错，而是把 zip 解压到了带空格或中文的路径，比如C:\Program Files\或D:\我的工具\，脚本里的路径拼接会直接崩掉。我一般会固定解压到C:\sonar\sonar-scanner-4.2.0.1873-windows这种纯英文无空格目录，后面所有配置都基于这个路径展开。

2. 从解压到第一次扫描：Windows 下的最小可复现路径

2.1 解压位置与目录结构确认

拿到 zip 后不要双击里面的 exe，它没有图形界面。正确做法是右键解压到目标目录，然后确认四个关键位置存在：

如果jre目录不存在，就必须保证系统JAVA_HOME指向 JDK 8 或 11。用java -version确认，输出里带1.8或11都行，带17以上在 4.2 这个版本上偶发类加载问题，建议换 JDK 11。

2.2 配置 sonar-scanner.properties

打开conf/sonar-scanner.properties，把服务端地址和默认编码写进去。下面是最小配置，注释保留原样即可：

# conf/sonar-scanner.properties # SonarQube 服务端地址，注意不要带结尾斜杠 sonar.host.url=http://192.168.1.50:9000 # 源码默认编码，Windows 下不写容易把中文注释扫成乱码 sonar.sourceEncoding=UTF-8 # 扫描临时目录，放在解压目录下避免权限问题 sonar.working.directory=../.scannerwork

sonar.host.url是唯一必须改的项，指向你的 SonarQube。sonar.sourceEncoding在 Windows 上强烈建议显式写 UTF-8，否则 GBK 编码的 Java 文件里的中文会变成问号，规则命中率直接失真。sonar.working.directory默认在系统临时目录，某些受限账户写不进去，改成解压目录下的相对路径最稳。

2.3 把 bin 目录加进 PATH

临时用可以每次敲全路径，长期用必须加环境变量。命令行方式（管理员 CMD）：

setx PATH "%PATH%;C:\sonar\sonar-scanner-4.2.0.1873-windows\bin" /M

/M表示写系统级变量，不加则只对当前用户生效。执行完要新开一个 CMD 窗口，旧窗口读不到新 PATH。验证：

sonar-scanner.bat -v

能打印出SonarScanner 4.2.0.1873就说明 PATH 生效。如果提示「不是内部或外部命令」，九成是 PATH 没刷新或路径写错，别急着重装。

2.4 在项目里发起第一次扫描

进入任意一个 Maven 或普通 Java 项目根目录，执行：

sonar-scanner.bat ^ -Dsonar.projectKey=my-demo ^ -Dsonar.projectName=MyDemo ^ -Dsonar.sources=src ^ -Dsonar.host.url=http://192.168.1.50:9000 ^ -Dsonar.login=你的token

Windows CMD 的换行符是^，PowerShell 里要用反引号。sonar.projectKey是服务端项目的唯一标识，第一次扫描会自动创建。sonar.sources指定源码目录，不写会扫整个项目包括node_modules，慢到怀疑人生。sonar.login用 SonarQube 里生成的 token，不要用账号密码，4.2 之后密码方式已不推荐。

扫描成功的标志是最后输出ANALYSIS SUCCESSFUL，并给一个http://.../dashboard?id=my-demo的链接。打开能看到问题列表就说明整条链路通了。第一次跑建议先用一个小项目验证，别直接上几十万行的大仓库，否则光等分析就能耗掉半小时。

3. 参数怎么设：让扫描结果和 CI 对齐的三个关键项

3.1 sonar.sources 与 sonar.exclusions 的边界

本地扫描和 CI 扫描结果对不上，最常见的原因是源码范围不一致。CI 上通常只扫src/main/java，本地图省事写了sonar.sources=.，把测试代码、生成代码、前端资源全扫进去，问题数自然翻倍。

正确做法是显式声明源码目录，并用排除规则挡掉不该扫的：

sonar.sources=src/main/java sonar.tests=src/test/java sonar.exclusions=**/generated/**,**/*.min.js,**/target/** sonar.test.exclusions=**/mock/**

sonar.sources和sonar.tests分开写，SonarQube 会用不同规则集处理。sonar.exclusions支持 Ant 风格通配，**匹配任意层级。target目录一定要排掉，否则编译产物会被当成源码分析，报一堆无意义的问题。我见过有人忘了排target，扫描时间从 2 分钟涨到 20 分钟，血泪经验。

3.2 覆盖率报告怎么接进来

光扫静态代码只能看坏味道和漏洞，要看覆盖率必须让单测先跑出报告，再告诉 scanner 报告在哪。以 JaCoCo 为例，先在pom.xml里配好插件，跑mvn test生成target/site/jacoco/jacoco.xml，然后扫描时加参数：

sonar-scanner.bat ^ -Dsonar.projectKey=my-demo ^ -Dsonar.sources=src/main/java ^ -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml ^ -Dsonar.login=你的token

sonar.coverage.jacoco.xmlReportPaths是 4.2 版本识别 JaCoCo 的标准参数，路径是相对项目根目录的。如果报告路径写错，扫描不会报错，只是覆盖率显示为 0，很容易误以为代码没测。验证方法是扫描日志里搜Coverage Report，能看到解析到的文件数就对了。多模块项目可以用逗号分隔多个报告路径。

3.3 分支与 PR 分析的参数差异

社区版 SonarQube 不支持分支分析，只有商业版才有sonar.branch.name。如果你在社区版上硬加这个参数，扫描会直接失败并提示不支持。本地开发一般扫主分支即可，需要区分不同特性分支时，常见做法是给sonar.projectKey加后缀，比如my-demo-feature-x，在服务端就是独立项目，互不干扰。

PR 分析需要sonar.pullrequest.key、sonar.pullrequest.branch、sonar.pullrequest.base三个参数同时给，缺一个就报错。这套参数通常由 CI 插件自动注入，本地手动跑意义不大。如果只是想看增量问题，用sonar.newCode.referenceBranch指定对比分支更实际。

4. 避坑与排查：Windows 上最容易翻车的五件事

4.1 现象：执行 sonar-scanner 提示找不到 Java

原因：zip 里没带 JRE，系统也没配JAVA_HOME，或者JAVA_HOME指向了 JRE 而非 JDK。scanner 启动脚本会优先读JAVA_HOME，读不到才找 PATH 里的java。

解决：确认JAVA_HOME指向 JDK 根目录（不是bin），且%JAVA_HOME%\bin\java.exe存在。CMD 里echo %JAVA_HOME%验证。改完环境变量必须新开窗口。

4.2 现象：扫描卡在「Load global settings」不动

原因：网络到 SonarQube 服务端不通，或者服务端地址写错。Windows 防火墙、公司网络策略都可能拦。

解决：先在浏览器打开sonar.host.url确认能访问，再用curl http://192.168.1.50:9000/api/server/version看是否返回版本号。如果浏览器能开但 scanner 卡住，检查是否配了系统代理导致请求被转发。scanner 默认读HTTP_PROXY环境变量，不需要代理时把它清掉。

4.3 现象：中文注释全变成乱码，规则误报激增

原因：源码是 GBK 编码，scanner 默认按系统编码读，Windows 中文版默认 GBK，但 SonarQube 服务端按 UTF-8 存，两边不一致。

解决：在sonar-scanner.properties里写死sonar.sourceEncoding=UTF-8，同时把源码文件本身转成 UTF-8。如果项目历史包袱重不能转码，就显式写sonar.sourceEncoding=GBK，但服务端展示仍可能异常，治本还是统一 UTF-8。

4.4 现象：扫描报「File is not under the project base directory」

原因：sonar.sources里写了绝对路径，或者路径里带了..跳出项目根目录。scanner 要求所有源码路径都在项目基目录之下。

解决：sonar.sources一律用相对路径，且不要用..。多模块项目在根目录跑，把各模块的相对路径用逗号列出来，比如module-a/src,module-b/src。

4.5 现象：token 认证失败，提示 401

原因：token 复制时带了空格，或者 token 已过期/被撤销，或者用了错误的用户 token。

解决：重新在 SonarQube 用户设置里生成 token，复制时注意首尾不要有空格。命令行里 token 含特殊字符时用双引号包起来。如果服务端开了强制 HTTPS，sonar.host.url也要同步改成https://，否则请求会被重定向后丢失认证头。

5. 进阶：把扫描嵌进 Windows 构建脚本与增量分析

5.1 用批处理封装可复用的扫描入口

每次敲一长串参数不现实，我习惯在项目根目录放一个scan.bat，把项目相关参数固化，只留 token 从环境变量读：

@echo off REM scan.bat - 本地扫描入口，token 从环境变量 SONAR_TOKEN 读取 set SONAR_TOKEN=你的token sonar-scanner.bat ^ -Dsonar.projectKey=my-demo ^ -Dsonar.projectName=MyDemo ^ -Dsonar.sources=src/main/java ^ -Dsonar.tests=src/test/java ^ -Dsonar.exclusions=**/generated/**,**/target/** ^ -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml ^ -Dsonar.host.url=http://192.168.1.50:9000 ^ -Dsonar.login=%SONAR_TOKEN%

把 token 写死在脚本里是坏习惯，正式项目应该从系统环境变量读，脚本里只写%SONAR_TOKEN%。这样脚本可以进版本库，token 留在本机。@echo off关掉命令回显，输出干净。这个脚本配合mvn test一起用，先跑测试生成覆盖率报告，再跑扫描，一条龙。

5.2 增量分析：只扫改动文件

全量扫描大项目动辄十几分钟，日常开发只需要看自己改的文件。SonarQube 本身不提供「只扫改动文件」的开关，但可以用sonar.inclusions临时限定范围：

sonar-scanner.bat ^ -Dsonar.projectKey=my-demo ^ -Dsonar.sources=src/main/java ^ -Dsonar.inclusions=src/main/java/com/demo/service/**/*.java ^ -Dsonar.login=%SONAR_TOKEN%

sonar.inclusions是白名单，只扫匹配的文件。注意这会让服务端本次分析只看到这些文件，历史问题不会消失，但新问题只报这部分。适合提交前快速自查，不适合作为正式门禁。正式门禁还是全量扫，保证基线一致。

5.3 验证扫描结果是否可信的三个检查点

跑完一次扫描，别只看「成功」两个字。我一般会做三个检查：第一，看日志里Index files的数量和项目实际文件数是否吻合，差太多说明sonar.sources写错了；第二，看覆盖率数字是否非零，为零先查报告路径；第三，打开服务端页面，随机点开两个问题，确认代码行号能对上，对不上多半是编码或路径问题。这三点过了，这次扫描结果才敢用来做质量判断。

5.4 版本升级的取舍

4.2.0.1873 是个偏老的版本，新版本 scanner 对 JDK 17 和新的 SonarQube 版本支持更好。但老版本的优势是稳定、依赖少，在 JDK 8 环境里几乎不会出幺蛾子。如果服务端是较新的 SonarQube（9.x 以上），建议同步升级 scanner，否则可能出现 API 不兼容导致部分指标缺失。升级时注意conf目录的配置要迁移，别直接覆盖。我自己的习惯是先在测试机跑通新版本，确认覆盖率、问题数和服务端一致后再推到构建机，避免升级当天全员扫描失败。希望帮到你。

本文还有配套的精品资源，点击获取