SonarQube怎么导入新项目 SonarQube项目Key怎么填写

在SonarQube里，新项目导入本质上有两条路，一条是先在平台里手工创建项目，再接扫描；另一条是第一次分析时直接把项目带上来，服务器会在收到一个不存在的项目Key后自动创建项目。官方文档也明确说明，手工创建时项目名和项目Key是本地项目创建的必要参数，而首次分析同样依赖项目Key完成识别。

一、SonarQube怎么导入新项目

这一部分先解决项目怎么进平台。更稳的做法是先确定你走手工创建还是扫描自动创建，再把名称、可见性和分析入口一次配齐，这样后面接CI或本地扫描时不容易反复返工。

1、先选导入方式

如果仓库托管在GitHub、GitLab、Azure DevOps或Bitbucket，可以走平台集成导入；如果只是普通本地项目或暂时不做仓库绑定，也可以直接手工创建本地项目。官方把这两类都列为标准建项路径。

2、手工创建时先填项目名和项目Key

手工创建本地项目时，项目名和项目Key是最基础也最必要的两项。若你团队项目很多，官方还建议用Web API的POST/api/projects/create来批量自动化创建，本质上同样只要求名称和项目Key。

3、也可以让第一次分析自动建项目

如果你不想先在界面里点创建，可以直接在第一次扫描时把sonar.projectKey带上。官方说明里写得很清楚，当服务器收到一个数据库里不存在的项目Key时，会自动创建对应项目。

4、导入后立刻补分析入口

项目进平台只是第一步，真正开始生效的是后续分析。官方项目分析说明建议在项目创建后继续配置分析方式，例如使用SonarScanner CLI、Maven或Gradle，把扫描接进本地或CI流程。

5、先用小范围代码跑一次首轮分析

首轮分析建议先确保扫描路径和项目Key都正常，再逐步补充分支、拉取请求或更复杂的质量门禁。这样更容易把“项目没导进来”和“分析参数没配好”分开。

6、项目创建后先检查是不是重复建项

如果同一仓库被不同projectKey重复分析，平台上就会出现多个看起来很像的项目。更稳的做法是团队先统一命名规则，再让所有扫描都复用同一套Key口径。

二、SonarQube项目Key怎么填写

这一部分解决的是项目Key到底怎么写才稳。项目Key不是随便起个名字就行，它既决定了平台如何识别项目，也直接影响后续历史是否能连续保留，所以填写时要优先保证唯一、稳定、可复用。

1、先把项目Key当成唯一标识

官方把sonar.projectKey定义为项目的唯一Key，这意味着它不是展示名，而是平台识别项目历史和后续分析归属的主键。名称可以更业务化，Key则要更稳定。

2、字符按官方允许范围填写

官方允许的字符范围包括字母、数字、短横线、下划线、点和冒号。较新的文档写法是可包含这些字符且最长可到400个字符，较旧和项目设置页还特别强调至少要包含一个非数字字符，所以实际填写时最好遵守这个更稳的交集规则。

3、Key尽量和仓库坐标保持一致

如果你用Maven或Gradle，官方文档说明projectKey可以有默认值，例如Maven常见就是groupId加artifactId这类坐标形式。实际项目里也建议沿用仓库、组名和模块名组合，这样最不容易撞Key。

4、不要把易变信息写进Key

分支名、日期、环境名如果频繁变化，就不适合直接写进项目Key，否则同一项目很容易被分析成多个新项目。更稳的做法是让Key代表项目本体，把分支和版本交给分析维度或CI变量处理。这个思路也和官方“项目Key可更新但历史会随Key迁移”的机制一致。

5、确实写错了再用Update Key改

如果项目已经建好但Key口径不理想，官方支持在Project Settings里用Update Key修改，而且不会丢失项目历史。也就是说，Key不是不能改，但最好在早期先定好，后面就少动。

6、团队里先定一套统一格式

更稳的写法通常是组织名冒号仓库名，或业务线点模块名这类形式，只要保证唯一、稳定、可读就行。关键不是花样多，而是所有扫描都用同一套规则，避免一个项目今天叫app:web，明天又叫app-web。

三、SonarQube项目导入后怎么复核

前两部分解决的是怎么建和怎么填，这一部分解决的是怎么确认项目真的导对了。更稳的做法不是看到平台里多了一个项目就结束，而是把Key、分析结果和扫描入口一起核一遍，确保后面CI接入时不会走偏。

1、先核项目名和Key是否一一对应

进入项目后先看名称是否便于识别，再看Key是否和你扫描配置里的一致。只要这两项对上，后面大多数分析历史就能连续积累。

2、再核首轮分析是否真正落进当前项目

首轮分析完成后，确认代码行数、语言和主分支结果是否正常显示。这样能尽早发现是不是扫描到了错误目录，或把结果打进了另一个同名项目。

3、最后把建项规则写进团队规范

把项目创建路径、projectKey命名规则和扫描接入方式固定下来，后面新仓库接入时直接复用。这样项目越多，反而越不容易乱。

总结

SonarQube导入新项目，最稳的路径是先选手工创建还是首次分析自动创建，再把项目名、项目Key和扫描入口一次配齐。项目Key填写时，优先保证唯一、稳定和团队统一，字符范围按官方允许的字母、数字、短横线、下划线、点和冒号来写，并尽量至少包含一个非数字字符。把这两步固定下来后，后面的CI接入和历史保留都会顺很多。