IntelliJ系列IDE中Node/Web monorepo自动补全生效的配置要求

针对你遇到的Nx monorepo本地库模块自动补全失效问题，结合IntelliJ的工作机制，要让自动补全完美生效，需满足以下要求：

一、TypeScript配置的精准识别与同步 #

• 标记根TS配置为项目级：在IntelliJ中，右键根目录的tsconfig.base.json，选择Mark as Project TypeScript Config，确保IDE优先使用该配置解析路径映射。你的paths配置本身正确，但如果IDE未将其识别为全局配置，会导致路径解析失效。
• 对齐TS版本与模块解析规则：在Settings > Languages & Frameworks > TypeScript中，选择Use TypeScript from node_modules（项目本地的TS版本），并确保moduleResolution（你的配置是node）和module（ESNext）与项目实际使用的模块系统匹配，避免IDE解析逻辑和编译逻辑不一致。
• 子项目TS配置的正确继承：每个应用/库的tsconfig.json必须通过"extends": "../tsconfig.base.json"（或对应相对路径）正确继承根配置，且不能覆盖baseUrl、paths等关键字段。

二、本地库模块的Package.json规范 #

• 完善入口与类型字段：
  • main/exports：确保exports字段覆盖所有导入场景（你的配置中仅设置了"."的import入口，若有子路径需补充），且main字段与exports的默认入口一致；对于ES模块，"type": "module"必须正确设置。
  • types：你的库配置中types指向./components.d.ts，需确保该文件已正确生成（可通过Nx的编译命令生成），且路径准确。若类型文件缺失或路径错误，IDE无法识别导出的符号。
• 本地模块链接的正确识别：Nx会自动处理本地模块的链接，但需确保IntelliJ未将本地库目录误判为外部依赖。可检查node_modules中对应@my-workspace/*模块的链接是否指向项目内的本地目录，若链接失效，重新执行nx reset或npm install修复。

三、IntelliJ项目结构与索引配置 #

• 标记源码目录为Sources Root：右键本地库的源码目录（如components/ui、components/demo-sdk），选择Mark Directory as > Sources Root，IntelliJ仅会对Sources Root内的文件进行索引，用于自动补全。
• 合理设置排除目录：在Settings > Directories中，将dist、tmp、node_modules（除本地链接模块外）标记为Excluded，避免IDE索引编译后的冗余文件，干扰源码的符号识别。
• 避免Gradle与Node索引冲突：由于你的项目混合了Gradle/Java和Node模块，需调整Gradle的索引策略：在Settings > Build, Execution, Deployment > Build Tools > Gradle中，将Build and run using设置为IntelliJ IDEA，并关闭Auto-reload changes（或调整为按需加载），防止Gradle的索引逻辑覆盖Node模块的解析。

四、插件与缓存的额外优化 #

• 确保核心插件启用并更新：在Settings > Plugins中，确认Node.js、JavaScript and TypeScript、Nx Console Idea插件已启用且为最新版本，过时插件可能存在兼容性问题。
• 深度清理缓存：除了Invalidate Caches and Restart，还需手动删除项目根目录的node_modules/.cache、.nx/cache，重新执行npm install或nx install，再重启IDE，彻底清除旧的索引缓存。
• 纯JS项目的补全支持：若使用原生JS而非TS，需在项目根目录创建jsconfig.json（结构类似tsconfig.base.json，包含baseUrl和paths），并在Settings > Languages & Frameworks > JavaScript中设置正确的JS版本（如ESNext），IDE即可提供自动补全。

内容的提问来源于stack exchange，提问作者Marian Klühspies