IntelliJ IDEA新建项目SDK选错导致pom.xml报红，需确保Project SDK、Language Level与pom.xml中java.version及maven-compiler-plugin版本一致；VS Code生成Java项目后需执行mvn compile才能创建src/main/java。

IntelliJ IDEA 里新建项目时选错 SDK 版本导致 pom.xml 报红

Java 项目模板生成后立即报错，常见原因是 IDE 默认用的 JDK 版本和 pom.xml 中 java.version 不一致。比如你选了 Maven 模板，默认用 JDK 21，但 pom.xml 写着 17，Maven 编译器插件就会拒绝执行。

• 新建项目前，先点 Project SDK 下拉框，手动选一个已安装且匹配你团队要求的 JDK（如 17 或 21）
• 如果已建好但报红，别急着删重来：打开 File → Project Structure → Project，确认 Project SDK 和 Project language level 一致；再检查 Modules → Sources 页签里的 Language level
• Maven 的 maven-compiler-plugin 版本要和 JDK 匹配——JDK 17 推荐用 3.11.0 及以上，否则可能忽略 --release 参数或编译失败

用 mvn archetype:generate 手动创建时卡在交互式选择

命令行跑 mvn archetype:generate 后停住不动，不是卡死，是它在等你输入编号选模板。很多人以为崩了，直接 Ctrl+C，结果啥也没生成。

• 加 -DarchetypeCatalog=internal 跳过远程索引加载，提速且避免网络超时
• 直接指定模板：例如 -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4，就不用手动选
• 必须显式提供 -DgroupId、-DartifactId、-Dversion，漏一个就会反复提示输入；建议写全：mvn archetype:generate -DgroupId=com.example -DartifactId=demo -Dversion=1.0.0 -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

VS Code + Extension Pack for Java 新建项目不生成 src/main/java

装了 Java 扩展包，右键“Generate Java Project”，结果只有 pom.xml 和空 src 文件夹，java 子目录没出来——这是默认模板没启用源码目录约定。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• 生成后立刻执行 mvn compile，Maven 会自动创建 src/main/java 和 src/test/java；不运行这步，VS Code 的 Java 语言服务器就识别不了源码根路径
• 如果想一步到位，改用户设置：打开 VS Code 设置，搜 java.configuration.updateBuildConfiguration，设为 interactive 或 always，下次生成会主动触发 Maven 初始化
• 注意 src 文件夹图标没变绿（表示未识别为 source root），说明 Java 扩展还没完成索引，等右下角 “Building workspace” 提示消失后再看

自定义模板被 IDE 忽略：archetype-catalog.xml 放哪都不生效

你按文档把自定义 archetype 打包、生成了 archetype-catalog.xml，也放进 ~/.m2/archetype-catalog.xml，但在 IntelliJ 里新建项目时还是看不到你的模板。

立即学习“Java免费学习笔记（深入）”；

• IDEA 不读全局 archetype-catalog.xml，它只认自己缓存里的索引。必须进 Preferences → Build → Maven → Archetypes，点 + 添加你本地的 archetype-catalog.xml 文件路径
• 添加后点 Reload project，不是重启 IDE——很多用户加完不点重载，以为失效
• 自定义 archetype 的 archetype-metadata.xml 里，<requiredproperty></requiredproperty> 如果写了 defaultValue 为空字符串，IDEA 会跳过该字段校验，导致生成失败但无提示；确保每个必填项都有非空默认值

实际用下来，最常被忽略的是：**Maven 项目结构是否被正确识别，不取决于文件夹是否存在，而取决于是否触发过一次成功的 mvn compile 或 IDE 的 Maven reload 动作**。没走这步，连 main 目录都可能被当成普通文件夹处理。