SonarQube 是目前主流的开源代码质量平台，它通过静态分析手段检测代码中的 Bug、安全漏洞、代码异味和重复代码，并以可视化的仪表盘呈现结果。对于 Vue 3 项目来说，团队协作开发时往往积累了大量 .vue 单文件组件、组合式 API 代码和 TypeScript 类型定义，这些内容如果没有统一的检测标准，代码腐化只是时间问题。将 SonarQube 引入 Vue 3 工程，可以让质量检测从口头约定变成可执行的门禁。
一、搭建 SonarQube 服务端环境
SonarQube 采用服务端加扫描器的架构。服务端负责存储分析结果、管理规则和生成报表，扫描器负责真正读取项目源码并执行分析。服务端推荐使用 Docker 方式部署，这是目前最省心的方案，一条命令即可拉起完整环境，不需要手动安装数据库和配置 Java 环境。
docker run -d --name sonarqube \ -p 9000:9000 \ -e SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true \ sonarqube:9.9-community
容器启动后访问 http://127.0.0.1:9000，默认账号密码都是 admin，首次登录会强制要求修改密码。登录后需要手动创建一个项目，记下生成的项目标识（project key），后面的扫描配置会用到。需要注意 SonarQube 对系统内存有一定要求，宿主机至少要保证 4G 可用内存，否则 Elasticsearch 组件会启动失败，这也是新手最常踩的坑。
如果公司内部有现成的 SonarQube 服务，可以直接跳过部署步骤，只要向管理员申请一个令牌（token）即可。令牌在“我的账户 - 安全”页面生成，生成后只显示一次，务必保存好。扫描器后续通过这个令牌向服务端上报分析结果，避免明文传输密码。
二、安装扫描器并编写配置文件
扫描器有几种形态：命令行版本 sonar-scanner、CI 环境专用版本，以及各构建工具的插件。对前端项目来说，直接使用独立的 sonar-scanner 最简单。以 npm 方式集成到 Vue 3 项目中是当下比较流行的做法，好处是依赖统一管理，团队成员克隆代码后无需额外安装工具。
npm install -D sonar-scanner
接着在项目根目录创建 sonar-project.properties 配置文件，这是整个集成的核心。下面是一份针对 Vue 3 加 TypeScript 项目的完整配置，可以直接复制使用后按实际情况修改。
# 项目唯一标识，与服务端创建的项目对应 sonar.projectKey=vue3-demo sonar.projectName=vue3-demo sonar.projectVersion=1.0.0 # 源码根目录 sonar.sources=src # 需要包含的文件类型，覆盖 vue 单文件组件和 ts 文件 sonar.inclusions=**/*.vue,**/*.ts,**/*.js # 排除测试文件、自动生成文件和构建产物 sonar.exclusions=**/*.spec.ts,**/tests/**,**/dist/**,**/node_modules/** # TypeScript 相关配置 sonar.typescript.node=node_modules sonar.javascript.lcov.reportPaths=coverage/lcov.info # 服务端地址与认证令牌 sonar.host.url=http://127.0.0.1:9000 sonar.login=你的令牌
配置里几个关键点值得展开说明。sonar.inclusions决定了哪些文件会被扫描，Vue 项目必须显式包含 .vue 文件，否则默认只分析 js 和 ts，单文件组件会被完全忽略。而 template 部分的模板代码，SonarQube 内置的 JavaScript 分析器已经可以解析，不需要额外配置 HTML 分析器。
sonar.exclusions同样重要。Vue CLI 或 Vite 生成的项目里，coverage 目录、dist 目录都不应该参与分析，它们要么是测试产物要么是构建结果，混进去会严重干扰重复率统计。测试文件单独排除是因为它们有专门的 sonar.tests 属性可以归到测试代码分类中，统计覆盖率时需要区分对待。
三、执行扫描并解读质量报告
在 package.json 中加一条脚本，执行后扫描器会读取配置、分析代码并把结果推送到服务端。
{
"scripts": {
"sonar": "sonar-scanner"
}
}执行 npm run sonar，日志中会出现 ANALYSIS SUCCESSFUL 字样表示分析完成。回到浏览器打开项目页面，就能看到完整的质量报告。报告主要包含几大板块：可靠性（Reliability）、安全性（Security）、可维护性（Maintainability）、覆盖率（Coverage）、重复率（Duplicated Lines）以及新代码（New Code）指标。
对于 Vue 3 项目，重点关注的通常是可维护性板块的代码异味（Code Smell）。常见的问题包括：某个组合式函数超过几百行、setup 内定义了过多响应式变量导致认知复杂度超标、v-for 渲染的列表缺少稳定的 key、以及 watch 监听器中没有清理副作用等。SonarQube 会逐条列出问题位置和严重级别，点击可以直达对应代码行，修改起来非常直观。
覆盖率数据需要额外说明。SonarQube 本身不做单元测试，它只读取测试工具产生的覆盖率报告。Vue 3 项目一般用 Vitest，执行 vitest run --coverage 后会在 coverage 目录生成 lcov.info 文件，配置中的 sonar.javascript.lcov.reportPaths 正是指向这个文件。如果路径配置错误，报告里的覆盖率会显示为 0，这是第二个高频踩坑点。
四、接入持续集成实现质量门禁
手动扫描只是第一步，真正发挥价值的是接入 CI 流程。以 GitLab CI 为例，在流水线中增加一个检测任务，每次合并请求都自动扫描，配合 SonarQube 的质量门禁（Quality Gate）做到不达标就拦截合并。
stages:
- test
- quality
sonarqube-check:
stage: quality
image:
name: sonarsource/sonar-scanner-cli:latest
entrypoint: [""]
variables:
SONAR_PROJECT_BASE_DIR: "$CI_PROJECT_DIR"
script:
- sonar-scanner
-Dsonar.projectKey=vue3-demo
-Dsonar.host.url=$SONAR_HOST_URL
-Dsonar.login=$SONAR_TOKEN
-Dsonar.qualitygate.wait=true
only:
- merge_requests
- main其中 -Dsonar.qualitygate.wait=true 参数会让任务等待服务端完成质量门禁计算，如果门禁不通过，CI 任务直接标记失败，合并请求随之被阻塞。服务端的门禁条件可以自定义，比如设定新代码覆盖率不低于 80%、不允许存在阻断级或严重级问题、新代码重复率不超过 3% 等，这些阈值应结合团队实际情况调整，初期可以放宽，随着代码质量改善逐步收紧。
还有一个细节是增量检测。SonarQube 区分整体代码和新代码，新代码的定义基于分支的基准，比如以 main 分支上一次分析为界。这样的设计让老代码的历史遗留问题不会阻塞新功能开发，团队只需要保证新写的代码达标即可，这也是 SonarQube 在存量项目中容易落地的原因。
五、针对 Vue 单文件组件的定制建议
默认规则集对 .vue 文件的适配已经比较完善，但实际使用中仍有几点可以优化。第一，可以在服务端关闭部分不适用的规则，比如针对 Options API 风格的某些检查在纯组合式 API 项目中意义不大。第二，对于 <style> 部分的 CSS 代码，如果重复率报警较多，可以考虑把公共样式抽离到独立 css 文件纳入扫描范围，减少误报干扰。
第二点建议是利用 sonar-project.properties 中的多配置组合。大型项目可以把 src 拆成多个模块分别配置 sources 和 exclusions，让报告结构更清晰。第三，如果团队已经在用 ESLint，两者并不冲突：ESLint 负责编码规范这类本地即时反馈的问题，SonarQube 负责架构层面的质量度量和趋势追踪，各司其职效果最好。把两者规则重叠的部分在 SonarQube 端关闭，避免开发者收到重复告警产生疲劳。
落地 SonarQube 不是一次性动作，建议每月查看一次质量趋势图，关注技术债务（Technical Debt）指标的变化方向。只要门禁持续生效，代码质量曲线自然会逐步上扬，Vue 3 项目也能长期保持健康的可维护状态。