Language Support for Java 全配置属性盘点
由 Red Hat 出品的 Language Support for Java 是 VSCode 生态中 Java 开发的基础扩展，提供代码补全、导航、格式化、重构、Maven 与 Gradle 导入、构建等核心语言能力。该扩展基于 Eclipse JDT 语言服务器，通过 LSP（Language Server Protocol）将完整的 Java 语言服务能力接入 VSCode，并支持语法服务器与标准服务器双服务器架构以平衡启动速度与功能完整性。该扩展的配置体系全部位于 settings.json 的 java.* 命名空间下，由扩展的 package.json 中 contributes.configuration 节点定义，按功能域划分为十三个配置组。
本文基于 vscode-java-main 项目源码，按扩展激活、项目导入、构建、代码编辑、代码导航、配置变更六大主流程逐一盘点全部可配置属性，并描述各属性在流程中的行为逻辑，帮助开发者精准驾驭每一个配置项。
配置属性总览
Language Support for Java 的全部配置属性均定义在 package.json 的 contributes.configuration 数组中，按功能域分为十三组。下文按组列出全部属性，包括属性名、类型、默认值及功能说明。部分已废弃属性在说明中标注废弃提示。
启动组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.home |
string | null |
null |
已废弃，指定启动语言服务器的 JDK 路径，请改用 java.jdt.ls.java.home |
java.jdt.ls.java.home |
string | null |
null |
指定启动语言服务器的 JDK 路径，需 JDK 21 或更高 |
java.jdt.ls.vmargs |
string | null |
-XX:+UseParallelGC -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -Dsun.zip.disableMemoryMapping=true -Xmx2G -Xms100m -Xlog:disable |
启动语言服务器的额外 VM 参数 |
java.server.launchMode |
enum: Standard, LightWeight, Hybrid |
Hybrid |
语言服务器的启动模式 |
java.configuration.workspaceCacheLimit |
integer | null |
90 |
保留未使用工作区缓存的天数，最小值 1 |
java.sharedIndexes.enabled |
enum: auto, on, off |
auto |
是否在不同工作区之间共享索引 |
java.sharedIndexes.location |
string |
"" |
共享索引的公共存储位置 |
java.jdt.ls.lombokSupport.enabled |
boolean |
true |
是否从项目类路径加载 Lombok 处理器 |
java.jdt.ls.protobufSupport.enabled |
boolean |
true |
是否自动将 Protobuf 输出源目录加入类路径 |
java.jdt.ls.aspectjSupport.enabled |
boolean |
false |
是否启用 Gradle 的 AspectJ 插件支持 |
java.jdt.ls.kotlinSupport.enabled |
boolean |
true |
是否启用 Gradle 的 Kotlin 插件支持 |
java.jdt.ls.scalaSupport.enabled |
boolean |
true |
是否启用 Gradle 的 Scala 插件支持 |
java.jdt.ls.groovySupport.enabled |
boolean |
true |
是否启用 Gradle 的 Groovy 插件支持 |
java.jdt.ls.androidSupport.enabled |
enum: auto, on, off |
auto |
是否启用 Android 项目导入 |
java.jdt.ls.javac.enabled |
enum: on, off |
off |
是否启用基于 Javac 的编译，需 Java 25 |
java.jdt.ls.appcds.enabled |
enum: auto, on, off |
auto |
是否启用 AppCDS 以加速扩展激活 |
java.trace.server |
enum: off, messages, verbose |
off |
VSCode 与语言服务器之间通信的追踪级别 |
redhat.telemetry.enabled |
boolean | null |
null |
是否向 Red Hat 发送使用数据与错误报告 |
项目导入与更新组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.import.projectSelection |
enum: manual, automatic |
automatic |
选择构建配置文件的导入方式 |
java.configuration.updateBuildConfiguration |
enum: disabled, interactive, automatic |
interactive |
构建文件修改后如何更新类路径 |
java.import.exclusions |
array |
["**/node_modules/**","**/.metadata/**","**/archetype-resources/**","**/META-INF/maven/**"] |
排除文件夹的 glob 模式 |
java.project.resourceFilters |
array |
["node_modules","\\.git"] |
从刷新中排除的文件与文件夹，使用正则表达式 |
java.configuration.checkProjectSettingsExclusions |
boolean |
false |
已废弃，是否从文件管理器排除生成的项目设置文件 |
java.import.generatesMetadataFilesAtProjectRoot |
boolean |
false |
是否在项目根目录生成元数据文件 |
java.project.importOnFirstTimeStartup |
enum: disabled, interactive, automatic |
automatic |
首次在 Hybrid 模式打开文件夹时是否导入项目 |
java.project.importHint |
boolean |
true |
项目导入被跳过时是否显示服务器模式切换提示 |
java.showBuildStatusOnStart.enabled |
enum: notification, terminal, off | boolean |
notification |
启动时构建状态的展示方式 |
java.project.encoding |
enum: ignore, warning, setDefault |
ignore |
项目编码设置的处理方式 |
非托管文件夹组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.project.sourcePaths |
array |
[] |
存放源文件的相对路径，仅在工作区作用域生效 |
java.project.outputPath |
string | null |
"" |
存放编译输出的相对路径，仅在工作区作用域生效 |
java.project.referencedLibraries |
array | object |
["lib/**/*.jar"] |
引用本地库的 glob 模式 |
Maven 组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.import.maven.enabled |
boolean |
true |
是否启用 Maven 导入器 |
java.import.maven.offline.enabled |
boolean |
false |
是否启用 Maven 离线模式 |
java.import.maven.disableTestClasspathFlag |
boolean |
false |
是否禁用测试类路径隔离 |
java.maven.downloadSources |
boolean |
false |
导入 Maven 项目时是否下载源码制品 |
java.maven.updateSnapshots |
boolean |
false |
是否强制更新快照与发布版本 |
java.configuration.maven.userSettings |
string |
null |
Maven 用户 settings.xml 路径 |
java.configuration.maven.globalSettings |
string |
null |
Maven 全局 settings.xml 路径 |
java.configuration.maven.notCoveredPluginExecutionSeverity |
enum: ignore, warning, error |
warning |
未覆盖插件执行的严重级别 |
java.configuration.maven.defaultMojoExecutionAction |
enum: ignore, warn, error, execute |
ignore |
无关联元数据时的默认 mojo 执行动作 |
java.configuration.maven.lifecycleMappings |
string |
null |
Maven 生命周期映射文件路径 |
Gradle 组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.import.gradle.enabled |
boolean |
true |
是否启用 Gradle 导入器 |
java.import.gradle.wrapper.enabled |
boolean |
true |
是否使用 gradle-wrapper.properties 中的 Gradle |
java.import.gradle.version |
string |
null |
wrapper 缺失或禁用时使用的 Gradle 版本 |
java.import.gradle.home |
string |
null |
Gradle 本地安装目录 |
java.import.gradle.java.home |
string |
null |
运行 Gradle 守护进程的 JVM 路径 |
java.import.gradle.user.home |
string |
null |
GRADLE_USER_HOME 设置 |
java.import.gradle.offline.enabled |
boolean |
false |
是否启用 Gradle 离线模式 |
java.import.gradle.arguments |
string |
null |
传递给 Gradle 的参数 |
java.import.gradle.jvmArguments |
string |
null |
传递给 Gradle 的 JVM 参数 |
java.import.gradle.annotationProcessing.enabled |
boolean |
true |
是否启用 Gradle 项目的注解处理 |
java.imports.gradle.wrapper.checksums |
array |
[] |
允许或禁止的 Gradle Wrapper SHA-256 校验和 |
构建组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.autobuild.enabled |
boolean |
true |
是否启用自动构建 |
java.maxConcurrentBuilds |
integer |
1 |
最大并发构建数，最小值 1 |
java.settings.url |
string |
null |
工作区 Java 设置的 URL 或文件路径 |
java.compile.nullAnalysis.nonnull |
array |
内置四项注解 | 空分析使用的 Nonnull 注解类型 |
java.compile.nullAnalysis.nullable |
array |
内置四项注解 | 空分析使用的 Nullable 注解类型 |
java.compile.nullAnalysis.nonnullbydefault |
array |
内置四项注解 | 空分析使用的 NonNullByDefault 注解类型 |
java.compile.nullAnalysis.mode |
enum: disabled, interactive, automatic |
interactive |
注解空分析的启用方式 |
java.errors.incompleteClasspath.severity |
enum: ignore, info, warning, error |
warning |
类路径不完整时的消息严重级别 |
已安装 JDK 组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.configuration.runtimes |
array |
[] |
将 Java 执行环境映射到本地 JDK |
java.configuration.detectJdksAtStart |
boolean |
true |
启动时是否自动检测本地已安装的 JDK |
格式化组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.format.enabled |
boolean |
true |
是否启用默认 Java 格式化器 |
java.format.settings.url |
string |
null |
Eclipse 格式化器 XML 设置的 URL 或路径 |
java.format.settings.profile |
string |
null |
格式化器配置文件中的 profile 名称 |
java.format.comments.enabled |
boolean |
true |
格式化时是否包含注释 |
java.format.onType.enabled |
boolean |
true |
输入 ;、回车或 } 时是否自动格式化 |
代码补全组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.completion.enabled |
boolean |
true |
是否启用代码补全 |
java.completion.engine |
enum: ecj, dom |
ecj |
代码补全引擎选择 |
java.completion.postfix.enabled |
boolean |
true |
是否启用后缀补全 |
java.completion.chain.enabled |
boolean |
false |
是否启用链式补全 |
java.completion.favoriteStaticMembers |
array |
内置 JUnit 与 Mockito 成员 | 即使缺少 import 也会推荐的静态成员 |
java.completion.filteredTypes |
array |
内置六项过滤 | 补全与导入中忽略的类型过滤器 |
java.completion.guessMethodArguments |
enum: auto, off, insertParameterNames, insertBestGuessedArguments |
auto |
补全时方法参数的填充方式 |
java.completion.matchCase |
enum: firstLetter, off |
firstLetter |
补全时是否匹配大小写 |
java.completion.importOrder |
array |
["#","java","javax","org","com",""] |
import 语句的排序顺序 |
java.completion.lazyResolveTextEdit.enabled |
boolean |
true |
是否延迟解析补全的文本编辑 |
java.completion.maxResults |
integer |
0 |
补全结果最大数量，0 表示不限制 |
java.signatureHelp.enabled |
boolean |
true |
是否启用签名帮助 |
java.signatureHelp.description.enabled |
boolean |
false |
签名帮助中是否显示描述 |
java.completion.collapseCompletionItems |
boolean |
false |
是否合并重载方法的补全项 |
代码生成组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.templates.newFile.enabled |
boolean |
true |
创建新 Java 文件时是否自动生成类体与包声明 |
java.templates.fileHeader |
array |
[] |
新文件的文件头注释模板 |
java.templates.typeComment |
array |
[] |
新类型的类型注释模板 |
java.templates.methodBody |
array |
内置默认方法体 | 未实现方法的方法体模板 |
java.templates.methodBodySuper |
array |
内置默认方法体 | 重写方法的方法体模板 |
java.templates.catchBody |
array |
内置默认 catch 块 | catch 块的代码模板 |
java.codeGeneration.insertionLocation |
enum: afterCursor, beforeCursor, lastMember |
afterCursor |
源码操作生成代码的插入位置 |
java.codeGeneration.addFinalForNewDeclaration |
enum: none, fields, variables, all |
none |
新声明是否生成 final 修饰符 |
java.codeGeneration.hashCodeEquals.useJava7Objects |
boolean |
false |
是否使用 Objects.hash 与 Objects.equals |
java.codeGeneration.hashCodeEquals.useInstanceof |
boolean |
false |
是否使用 instanceof 比较类型 |
java.codeGeneration.useBlocks |
boolean |
false |
是否在 if 语句中使用代码块 |
java.codeGeneration.generateComments |
boolean |
false |
是否生成方法注释 |
java.codeGeneration.generateCommentsInMarkdown |
boolean |
false |
是否以 Markdown 风格生成 Javadoc，需合规级别 23 以上 |
java.codeGeneration.toString.template |
string |
${object.className} [${member.name()}=${member.value}, ${otherMembers}] |
toString 方法的生成模板 |
java.codeGeneration.toString.codeStyle |
enum: STRING_CONCATENATION, STRING_BUILDER, STRING_BUILDER_CHAINED, STRING_FORMAT |
STRING_CONCATENATION |
toString 方法的代码风格 |
java.codeGeneration.toString.skipNullValues |
boolean |
false |
toString 是否跳过 null 值 |
java.codeGeneration.toString.listArrayContents |
boolean |
true |
toString 是否列出数组内容 |
java.codeGeneration.toString.limitElements |
integer |
0 |
数组或集合列出元素的最大数量，0 表示全部 |
java.edit.smartSemicolonDetection.enabled |
boolean |
false |
是否启用智能分号检测 |
代码操作组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.cleanup.actions |
array |
["renameFileToType"] |
保存或执行清理命令时运行的清理操作列表 |
java.cleanup.actionsOnSave |
array |
[] |
已废弃，请改用 java.cleanup.actions |
java.saveActions.cleanup |
boolean |
true |
是否在保存时执行清理操作 |
java.saveActions.organizeImports |
boolean |
false |
已废弃，请改用 editor.codeActionsOnSave |
java.updateImportsOnPaste.enabled |
boolean |
true |
粘贴代码时是否自动整理导入 |
java.sources.organizeImports.starThreshold |
integer |
99 |
触发星号导入的普通 import 数量阈值，最小值 1 |
java.sources.organizeImports.staticStarThreshold |
integer |
99 |
触发星号导入的静态 import 数量阈值，最小值 1 |
java.quickfix.showAt |
enum: line, problem |
line |
快速修复的展示位置 |
java.codeAction.sortMembers.avoidVolatileChanges |
boolean |
true |
排序成员时是否避免语义变更 |
java.refactoring.extract.interface.replace |
boolean |
true |
提取接口后是否替换所有子类型引用 |
代码导航组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.hover.javadoc.enabled |
boolean |
true |
悬停时是否显示 Javadoc |
java.referencesCodeLens.enabled |
boolean |
false |
是否启用引用 CodeLens |
java.referencesCodeLens.includeFields |
boolean |
false |
引用 CodeLens 是否包含字段 |
java.implementationCodeLens |
enum: none, types, methods, all |
none |
实现 CodeLens 的启用类别 |
java.references.includeAccessors |
boolean |
true |
查找引用时是否包含 getter 与 setter |
java.references.includeDeclarations |
boolean |
true |
查找引用时是否包含声明 |
java.references.includeDecompiledSources |
boolean |
true |
查找引用时是否包含反编译源码 |
java.symbols.includeSourceMethodDeclarations |
boolean |
false |
符号搜索是否包含源码中的方法声明 |
java.symbols.includeGeneratedCode |
boolean |
false |
文档大纲是否包含生成的代码 |
java.typeHierarchy.lazyLoad |
boolean |
false |
类型层次是否懒加载 |
java.inlayHints.parameterNames.enabled |
enum: none, literals, all |
literals |
参数名内联提示的启用范围 |
java.inlayHints.parameterNames.suppressWhenSameNameNumbered |
boolean |
true |
是否抑制同名称编号参数的提示 |
java.inlayHints.parameterNames.exclusions |
array |
[] |
禁用参数名提示的方法模式列表 |
java.inlayHints.variableTypes.enabled |
boolean |
false |
是否启用隐式变量类型内联提示 |
java.inlayHints.parameterTypes.enabled |
boolean |
false |
是否启用 lambda 参数类型内联提示 |
java.inlayHints.formatParameters.enabled |
boolean |
false |
是否启用格式化字符串参数内联提示 |
java.search.scope |
enum: all, main |
all |
查找引用、调用层次、工作区符号的搜索范围 |
其他组
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
java.eclipse.downloadSources |
boolean |
false |
是否为 Eclipse 项目下载 Maven 源码制品 |
java.contentProvider.preferred |
string |
null |
首选内容提供者（第三方反编译器 ID） |
java.foldingRange.enabled |
boolean |
true |
是否启用智能折叠范围 |
java.selectionRange.enabled |
boolean |
true |
是否启用智能选择 |
java.edit.validateAllOpenBuffersOnChanges |
boolean |
false |
编辑 Java 文件时是否重新校验所有打开文件 |
java.diagnostic.filter |
array |
[] |
不报告诊断的文件模式列表 |
java.editor.reloadChangedSources |
enum: ask, auto, manual |
ask |
源码 jar 变更时如何重载打开的类文件源码 |
runtimes 子属性
| 子属性名 | 类型 | 说明 |
|---|---|---|
name |
enum |
Java 执行环境名称，如 JavaSE-21，必须唯一 |
path |
string |
JDK 安装目录，非 bin 路径 |
sources |
string |
JDK 源码路径 |
javadoc |
string |
JDK javadoc 路径 |
default |
boolean |
是否为默认运行时，仅一个可为默认 |
扩展激活与语言服务器启动流程
扩展在打开包含 pom.xml、build.gradle、.classpath 等构建文件的工作区时自动激活。激活后首先加载支持的 JRE 名称列表并初始化 Java 运行时管理器，随后解析运行环境需求、确定服务器启动模式、准备启动参数并启动语言服务器进程。
java.server.launchMode 是决定服务器架构的核心配置。扩展读取该配置后确定启动模式，默认为 Hybrid。若工作区处于不可信状态，则无论配置为何值都强制降级为 LightWeight 模式。三种模式的行为差异为：Hybrid 模式同时启动语法服务器与标准服务器，语法服务器在标准服务器就绪前提供大纲、导航、Javadoc、语法错误等语法特性，标准服务器就绪后语法服务器停止；Standard 模式仅启动标准服务器，提供完整功能但不具备语法服务器的快速响应优势；LightWeight 模式仅启动语法服务器，启动成本低但只提供语法特性。是否需要语法服务器的判断为：若启动模式不为 Standard 则需要语法服务器；是否需要标准服务器的判断为：若启动模式不为 LightWeight 则需要标准服务器。当用户通过命令切换到 Standard 模式时，会停止语法服务器并启动标准服务器，同时触发状态栏与文件事件处理器的更新。
java.jdt.ls.java.home 与 java.home 共同决定启动语言服务器所用的 JDK 路径。扩展首先尝试读取 java.jdt.ls.java.home 的工作区值，若工作区值存在且工作区不可信，则弹窗询问是否允许该工作区设置此变量：若允许则记录并使用，若不允许则清除工作区值并回退到全局值。若 java.jdt.ls.java.home 为空，则回退到已废弃的 java.home，回退时同样执行工作区值的可信性校验。两者均要求 JDK 版本达到最低要求：若 java.jdt.ls.javac.enabled 为 on 则最低要求 Java 25，否则最低要求 Java 21。若配置的 JDK 版本不满足要求但已设置，扩展会提示该 JDK 不满足最低版本要求并不会使用，然后从环境变量、PATH、SDKMAN、jEnv、jabba、公共目录等位置搜索满足版本要求的 JDK。若配置的 JDK 路径不存在或不是有效 JDK，则抛出错误并终止激活。解析出的 JDK 路径会作为语言服务器进程的可执行命令路径。
java.jdt.ls.vmargs 传递给语言服务器进程的 VM 参数。扩展首先检查工作区值是否包含 javaagent 标志：若包含且工作区不可信，则弹窗询问是否允许使用该 javaagent；若不允许则清除工作区值并回退到全局值。解析 VM 参数时扩展会自动追加若干参数：若未包含 DetectVMInstallationsJob.disabled 则追加为 true 以禁用 VM 检测任务；若未包含 file.encoding 则追加从工作区编码设置解析出的编码；若未包含 Xlog 设置则追加 Xlog:disable 以关闭 GC 日志。对于标准服务器还会追加堆转储相关参数：若未包含 HeapDumpOnOutOfMemoryError 则追加以在内存溢出时生成堆转储，若未包含堆转储路径则追加工作区目录作为转储路径，若未包含依赖收集器实现则追加广度优先策略。若 java.jdt.ls.lombokSupport.enabled 为 true，则在参数中追加 Lombok javaagent 路径。java.import.generatesMetadataFilesAtProjectRoot 的值会作为系统属性传递给服务器进程。
java.jdt.ls.javac.enabled 控制是否启用基于 Javac 的编译。若为 on，扩展将最低 JDK 版本要求提升到 25，并在启动参数中追加大量 jdk.compiler 模块的 --add-opens 以开放编译器内部 API，同时设置若干系统属性将编译单元解析器、编译器工厂、代码补全、搜索索引等切换为 DOM 实现。若同时 java.completion.engine 为 dom，则额外追加 DOM 补全开关属性。若为 off，则使用默认的 ECJ 编译器，java.completion.engine 的 dom 选项不生效。
java.jdt.ls.appcds.enabled 控制 AppCDS（应用类数据共享）的启用，仅对标准服务器生效。若为 on 则始终启用；若为 auto 则仅在预发布版本或 Insiders 编辑器中启用；若为 off 则不启用。启用时会追加解锁诊断 VM 选项、允许带 javaagent 归档、自动创建共享归档、共享归档文件路径等参数，归档文件存放在扩展全局存储目录下按版本号划分的子目录中。但若 VM 参数中已包含共享归档文件路径，或当前处于 JDWP 调试模式，则不追加 AppCDS 参数。
java.sharedIndexes.enabled 与 java.sharedIndexes.location 控制共享索引功能，仅对标准服务器生效。若 enabled 为 auto，则在 Insiders 编辑器中视为 on，否则视为 off。若最终为 on，则解析索引位置：若 java.sharedIndexes.location 已配置则展开其中的 home 目录符号后使用，否则按平台选择默认位置（Windows 优先 APPDATA 下的 .jdt/index，macOS 使用 ~/Library/Caches/.jdt/index，Linux 优先 XDG_CACHE_HOME 下的 .jdt/index）。解析出位置后确保目录存在，若创建失败则回退到本地索引。最终将索引位置作为系统属性传递给服务器。Lombok、Protobuf、AspectJ、Kotlin、Scala、Groovy、Android 等语言与框架支持开关在启动时作为初始化选项传递给语言服务器，由服务器决定是否加载对应插件。
java.trace.server 控制 LSP 通信的追踪级别，影响语言客户端的日志输出详细程度。redhat.telemetry.enabled 控制是否收集使用数据与错误报告，在扩展激活时初始化遥测模块，若启用则收集 Java 配置信息与启动事件等数据。java.configuration.workspaceCacheLimit 控制未使用工作区缓存的保留天数，超过此天数的缓存数据可能被清理。
java.showBuildStatusOnStart.enabled 控制启动时构建状态的展示方式。若为 terminal 则在标准服务器启动时执行服务器任务状态展示命令，将构建状态输出到终端；若为 notification（默认）则通过进度通知展示；若为 off 则不展示任何构建状态。该配置在标准服务器初始化阶段读取。
项目导入流程
项目导入流程在标准服务器启动时触发。当启动模式为 Hybrid 且工作区首次打开（即工作区数据目录中不存在 .metadata/.plugins）时，流程会读取 java.project.importOnFirstTimeStartup 决定是否导入项目：若为 disabled，或当前为 Web 版 VS Code，则保持 LightWeight 模式不启动标准服务器；若为 interactive 且工作区包含构建文件，则先保持 LightWeight 模式，弹窗询问是否导入项目，用户选择导入后才启动标准服务器；若为 automatic，则直接启动标准服务器导入项目。
java.project.importHint 影响 interactive 模式下的提示行为。当项目导入被跳过时，若该配置为 true，扩展会在状态栏显示提示信息，告知用户语言服务器运行在 LightWeight 模式，可点击火箭图标稍后导入项目。用户关闭提示后该配置会被写入为 false 以避免重复打扰。
java.import.projectSelection 控制构建配置文件的选择方式。若为 automatic，扩展自动扫描并导入所有构建文件。若为 manual，扩展按以下顺序判断：若用户之前已选择过"全部导入"，则使用自动模式；若工作区无可选择的构建文件，则使用自动模式；若已缓存之前手动选择的构建文件，则使用手动模式直接导入缓存的文件；否则弹窗询问用户选择"全部导入"还是"让我选择"，前者记为自动模式，后者进入手动选择流程，用户可在构建文件列表中勾选要导入的文件。
java.import.exclusions 与 java.project.resourceFilters 都用于排除文件夹，但机制不同。java.import.exclusions 使用 glob 模式，在项目导入阶段排除匹配的文件夹不参与导入，支持 ! 取反以允许子文件夹导入，模式顺序会影响结果。java.project.resourceFilters 使用正则表达式，在文件刷新阶段排除匹配的文件与文件夹不参与刷新，用于提升整体性能，如 node_modules 与 .git 默认被排除。
java.configuration.updateBuildConfiguration 控制构建文件修改后的类路径更新行为。若为 disabled，构建文件修改后不自动更新类路径；若为 interactive，修改后弹窗询问是否更新；若为 automatic，修改后自动更新。该配置可通过通知中的快捷操作被用户修改并持久化。
java.configuration.runtimes 与 java.configuration.detectJdksAtStart 共同决定项目的 JDK 运行时映射。detectJdksAtStart 为 true 时，扩展在启动时自动检测本地已安装的 JDK。runtimes 将 Java 执行环境名称（如 JavaSE-21）映射到本地 JDK 路径，可指定源码路径、javadoc 路径与是否为默认。若自动检测到的 JDK 版本与 runtimes 中已配置的版本相同，则优先使用 runtimes 中配置的版本。在解析默认项目 JDK 时，扩展遵循 java.jdt.ls.java.home 大于 java.home 大于环境变量大于 PATH 大于 runtimes 中默认项的优先级顺序。当无法从任何来源获取有效 JDK 时，扩展会提示用户下载安装 JDK。
java.import.generatesMetadataFilesAtProjectRoot 控制项目元数据文件（.project、.classpath、.factorypath、.settings/）的生成位置。该值在启动时作为系统属性传递给语言服务器。当该配置变更时，扩展会创建清理标记文件触发工作区缓存清理，因为元数据文件生成位置的改变需要清理后重启才能生效。java.configuration.checkProjectSettingsExclusions 是已废弃的配置，开启时会将默认隐藏的元数据文件加入 files.exclude 设置中。
java.project.encoding 控制项目编码设置的处理方式。若为 ignore，不处理项目编码；若为 warning，当项目无显式编码设置时显示警告；若为 setDefault，将默认工作区编码设置设为项目编码。java.configuration.workspaceCacheLimit 控制未使用工作区缓存的保留天数，超过此天数的缓存可能被清理。
对于非托管文件夹（无 Maven 或 Gradle 构建文件的项目），java.project.sourcePaths 指定源文件目录的相对路径，java.project.outputPath 指定编译输出的相对路径，java.project.referencedLibraries 指定引用的本地库。这三项仅在工作区作用域生效，不影响 Maven 或 Gradle 项目。referencedLibraries 支持数组形式（仅包含路径）与对象形式（包含 include、exclude、sources 三个子字段）。
构建流程
构建流程在标准服务器就绪后运行。java.autobuild.enabled 控制是否在文件保存或变更时自动触发构建。若为 true，语言服务器自动监听文件变更并在需要时增量构建；若为 false，用户需通过手动执行工作区编译命令触发构建。java.maxConcurrentBuilds 限制同时进行的项目构建数量，达到上限后新构建任务排队等待，最小值为 1。
java.compile.nullAnalysis.mode 控制基于注解的空指针分析的启用方式。java.compile.nullAnalysis.nonnull、nullable、nonnullbydefault 三个数组分别指定 Nonnull、Nullable、NonNullByDefault 注解类型，扩展按数组顺序优先使用项目依赖中存在的注解。若 mode 为 disabled，三个注解数组被忽略，空分析完全不启用；若为 interactive，首次检测到可启用空分析时弹窗询问用户，用户的选择会被持久化写入该配置；若为 automatic，自动启用空分析无需询问。
java.errors.incompleteClasspath.severity 控制类路径不完整时提示消息的严重级别。当 Java 文件的类路径不完整时，扩展按此配置的级别报告诊断：ignore 不报告，info 报告为信息，warning 报告为警告，error 报告为错误。用户可通过通知中的快捷操作修改此配置并持久化。java.settings.url 指定外部 Java 设置文件的 URL 或路径，加载后覆盖默认配置选项。
java.project.encoding 在构建阶段影响编译编码。若为 setDefault，扩展将工作区默认编码设为项目编码；若为 warning，当项目无显式编码时显示警告。Maven 相关配置（java.import.maven.enabled、java.import.maven.offline.enabled、java.maven.downloadSources、java.maven.updateSnapshots 等）与 Gradle 相关配置（java.import.gradle.enabled、java.import.gradle.wrapper.enabled、java.import.gradle.version 等）在项目导入阶段由语言服务器读取，控制导入器启用、离线模式、源码下载、wrapper 使用等行为。java.imports.gradle.wrapper.checksums 定义允许或禁止的 Gradle Wrapper SHA-256 校验和，当遇到未在列表中的 wrapper 时弹窗询问是否信任，用户的选择会被写入该配置。
代码编辑流程
代码编辑流程涵盖代码补全、格式化、代码生成、代码清理等子流程，各子流程在用户编辑 Java 文件时按需触发。
java.completion.guessMethodArguments 控制补全方法时参数的填充方式。若为 auto，则在 Insiders 编辑器中等效于 off，在其他编辑器中等效于 insertBestGuessedArguments；若为 off，补全时不插入方法参数；若为 insertParameterNames，插入参数名称；若为 insertBestGuessedArguments，根据代码上下文猜测最佳参数插入。java.completion.collapseCompletionItems 若为 true，会将重载方法合并为单个补全项，且会覆盖 guessMethodArguments 的行为。java.completion.matchCase 控制补全时的大小写匹配：若为 firstLetter，优先匹配首字母大小写；若为 off，不匹配大小写。java.completion.maxResults 限制补全结果数量，0 表示不限制，在性能问题时可设置合理上限。java.completion.engine 选择补全引擎，dom 引擎需要 java.jdt.ls.javac.enabled 为 on 才生效，否则使用默认的 ECJ 引擎。java.completion.filteredTypes 定义的类型过滤器会同时在补全建议与导入整理中生效，匹配的全限定名类型被忽略。java.completion.importOrder 定义 import 语句的排序顺序，静态导入以 # 前缀标识。java.completion.lazyResolveTextEdit.enabled 控制是否延迟解析补全项的文本编辑以提升响应速度。java.signatureHelp.enabled 与 java.signatureHelp.description.enabled 控制签名帮助的启用与描述显示。
java.format.enabled 控制默认 Java 格式化器的启用。java.format.settings.url 指定 Eclipse 格式化器 XML 设置文件的 URL 或路径，加载后作为格式化规则。java.format.settings.profile 指定格式化器配置文件中的 profile 名称，用于在 XML 中包含多个 profile 时选择。java.format.comments.enabled 控制格式化时是否包含注释。java.format.onType.enabled 控制输入 ;、回车或 } 时是否自动触发格式化。
java.cleanup.actions 定义保存或执行清理命令时运行的清理操作列表，支持 qualifyMembers、addOverride、stringConcatToTextBlock、instanceofPatternMatch、lambdaExpression、switchExpression、tryWithResource、organizeImports 等多种操作。java.saveActions.cleanup 控制是否在保存时执行清理操作：若为 true，保存时执行 java.cleanup.actions 中配置的清理操作；若为 false，保存时不执行清理，但手动执行清理命令时仍会运行。java.saveActions.organizeImports 已废弃，建议改用 VSCode 内置的 editor.codeActionsOnSave 配置。java.updateImportsOnPaste.enabled 控制粘贴代码时是否自动整理导入语句。java.sources.organizeImports.starThreshold 与 staticStarThreshold 控制星号导入的触发阈值：当同一包下的普通 import 数量达到 starThreshold 时改为星号导入，静态 import 数量达到 staticStarThreshold 时改为静态星号导入。java.quickfix.showAt 控制快速修复的展示位置：line 在行级别展示，problem 在问题级别展示。
java.templates.newFile.enabled 控制创建新 Java 文件时是否自动生成类体与包声明，若为 false 则创建空文件。java.templates.fileHeader 与 java.templates.typeComment 分别定义新文件的文件头注释与类型注释模板，支持使用预定义变量。java.templates.methodBody、java.templates.methodBodySuper、java.templates.catchBody 分别定义未实现方法的方法体、重写方法的方法体、catch 块的代码模板，均支持预定义变量替换。java.codeGeneration.insertionLocation 控制源码操作生成代码的插入位置：afterCursor 插入到光标所在成员之后，beforeCursor 插入到光标所在成员之前，lastMember 作为目标类型的最后一个成员插入。java.codeGeneration.addFinalForNewDeclaration 控制新声明是否生成 final 修饰符：none 不生成，fields 仅字段生成，variables 仅变量生成，all 全部生成。java.codeGeneration.toString 系列配置控制 toString 方法的生成行为，包括模板、代码风格、是否跳过 null 值、是否列出数组内容、列出元素的最大数量。java.edit.smartSemicolonDetection.enabled 控制智能分号检测的启用，开启后在行尾输入分号时会自动将分号定位到行末。
java.edit.validateAllOpenBuffersOnChanges 控制编辑 Java 文件时是否重新校验所有打开的 Java 文件。若为 true，任一 Java 文件变更都会触发所有打开 Java 文件的诊断重新检查；若为 false，仅校验当前编辑的文件。java.diagnostic.filter 指定不报告诊断的文件模式列表，匹配的文件不显示诊断信息。java.foldingRange.enabled 与 java.selectionRange.enabled 分别控制智能折叠范围与智能选择的启用，关闭后回退到 VSCode 默认的缩进折叠与基于单词的选择。java.editor.reloadChangedSources 控制源码 jar 文件变更时如何重载打开的类文件源码：ask 询问用户，auto 自动重载，manual 手动重载。java.contentProvider.preferred 指定首选的内容提供者（通常是第三方反编译器 ID），用于显示类文件内容。
代码导航流程
代码导航流程在用户执行查找引用、跳转定义、查看类型层次、悬停查看文档等操作时触发。
java.referencesCodeLens.enabled 控制引用 CodeLens 的启用，在类型与方法上方显示引用计数。java.referencesCodeLens.includeFields 控制引用 CodeLens 是否在字段上显示。java.implementationCodeLens 控制实现 CodeLens 的启用类别：none 禁用，types 仅类型显示，methods 仅方法显示，all 类型与方法均显示。java.hover.javadoc.enabled 控制悬停时是否显示 Javadoc 文档。
java.references.includeAccessors、java.references.includeDeclarations、java.references.includeDecompiledSources 三个配置共同影响查找引用的结果范围。includeAccessors 为 true 时在查找引用结果中包含 getter、setter 与 builder 或构造函数；includeDeclarations 为 true 时包含声明本身；includeDecompiledSources 为 true 时包含反编译的源码引用。java.symbols.includeSourceMethodDeclarations 控制符号搜索是否包含源码中的方法声明。java.symbols.includeGeneratedCode 控制文档大纲是否包含生成的代码（如 Lombok 生成的 getter、setter、构造函数）。java.typeHierarchy.lazyLoad 控制类型层次的加载方式：若为 true，类型层次懒加载，每个类型需手动展开才能加载内容，可节省加载时间；若为 false，一次性加载全部内容。
java.inlayHints.parameterNames.enabled 控制参数名内联提示的启用范围：none 禁用，literals 仅对字面量参数显示，all 对字面量与非字面量参数均显示。java.inlayHints.parameterNames.suppressWhenSameNameNumbered 控制是否抑制同名称编号参数的提示：若为 true，当参数遵循 arg0、arg1 等同名称编号模式时不显示提示。java.inlayHints.parameterNames.exclusions 定义禁用参数名提示的方法模式列表，支持多种匹配语法：java.lang.Math.* 匹配某类型的所有方法，*.Arrays.asList 匹配指定类型名与方法名，*.println(*) 匹配指定方法名，(from, to) 匹配指定参数名，(arg*) 匹配参数名前缀。java.inlayHints.variableTypes.enabled 控制是否对隐式类型变量（var）显示类型提示。java.inlayHints.parameterTypes.enabled 控制是否对 lambda 参数显示类型提示。java.inlayHints.formatParameters.enabled 控制是否对格式化字符串（如 String.format）显示参数与格式说明符的对应关系提示。
java.search.scope 控制查找引用、调用层次、工作区符号的搜索范围：all 在所有类路径条目（包括引用库与项目）中搜索，main 在排除测试类路径的所有类路径条目中搜索。
配置变更与热更新流程
扩展在激活时注册配置变更监听器，当 java.* 命名空间下的配置发生变更时执行热更新决策。决策逻辑将配置变更分为三类：需要清理重启的变更、需要重新加载窗口的变更、可直接热更新的变更。
需要清理重启的变更是 java.import.generatesMetadataFilesAtProjectRoot 的变更，因为元数据文件生成位置的改变需要清理工作区缓存后重启才能生效。扩展检测到该变更时创建清理标记文件，随后提示用户重新加载窗口。
需要重新加载窗口的变更包括以下配置项的变更：java.jdt.ls.java.home、java.home、java.jdt.ls.vmargs、java.server.launchMode、java.sharedIndexes.location、java.trace.server 对应的传输模式、java.diagnostic.filter、java.jdt.ls.javac.enabled、java.completion.engine、java.jdt.ls.appcds.enabled。这些配置在语言服务器启动时读取并固化为进程参数，运行时变更无法直接传递给已运行的进程，因此需要重新加载窗口以重启语言服务器。扩展检测到这些变更时提示用户重新加载。
java.jdt.ls.lombokSupport.enabled 的变更单独处理：若从关闭切换为开启，提示用户重新加载窗口以加载 Lombok 支持；若从开启切换为关闭，先清理 Lombok 缓存再提示重新加载。
其余配置项（如代码补全、格式化、代码生成、代码导航、清理操作等）的变更可通过 LSP 的配置变更通知直接热更新到语言服务器，无需重新加载窗口。扩展在检测到这些变更时通过配置同步机制将新值推送给语言服务器，由服务器动态调整行为。java.configuration.checkProjectSettingsExclusions 的变更是例外，开启时会立即将默认隐藏的元数据文件加入 files.exclude 设置，无需重启。
配置最佳实践
对于启动性能敏感的场景，建议将 java.server.launchMode 保持为 Hybrid 以获得语法服务器的快速响应，同时启用 java.jdt.ls.appcds.enabled 为 auto 让 Insiders 版本自动获得 AppCDS 加速。若内存有限，可通过 java.jdt.ls.vmargs 调整 -Xmx 参数，但建议不低于 1G 以避免内存溢出导致功能异常。
对于大型工作区，建议启用 java.sharedIndexes.enabled 为 on 以加速跨工作区索引复用，配置 java.project.resourceFilters 排除 node_modules、.git 等无关目录以减少刷新开销，适当调大 java.maxConcurrentBuilds 以利用多核加速构建。
对于多 JDK 项目，建议通过 java.configuration.runtimes 显式映射各版本 JDK 并指定默认运行时，同时保持 java.configuration.detectJdksAtStart 为 true 以自动补充未显式配置的 JDK。将 java.jdt.ls.java.home 指向满足最低版本要求的 JDK 以启动语言服务器，项目编译则使用 runtimes 中映射的对应版本 JDK。
对于代码质量要求较高的团队，建议通过 java.cleanup.actions 配置统一的清理操作列表并启用 java.saveActions.cleanup，通过 java.format.settings.url 指定共享的 Eclipse 格式化器 XML 以统一代码风格，通过 java.completion.importOrder 统一 import 排序规则。
对于调试与排障场景，建议将 java.trace.server 设为 verbose 以获取详细的 LSP 通信日志，将 java.edit.validateAllOpenBuffersOnChanges 设为 true 以便在编辑时发现关联文件的编译错误，通过 java.diagnostic.filter 排除生成代码的误报告警。
浙公网安备 33010602011771号