IntelliJ IDEA中自定义注释模板不生效？

Question

在 IntelliJ IDEA 中配置了自定义 File Header 或 Live Template 注释模板（如 `/** @author $USER$ @date $DATE$ */`），但新建文件时注释未自动插入，或输入缩写（如 `main`）后不触发模板展开。常见原因包括：① 模板作用域（Applicable in）未正确勾选对应文件类型（如 Java、Kotlin）；② 模板启用状态为 disabled（右上角开关关闭）；③ File Header 模板仅对新创建的文件生效，对已存在文件无效且不会自动补全；④ 使用了错误的变量名（如 `$YEAR$` 有效，但 `$TIME_STAMP$` 非标准）；⑤ 插件冲突（如 CodeGlance、Rainbow Brackets）干扰模板解析；⑥ IDE 缓存异常或配置未同步至当前项目（需检查是 Project-level 还是 Default Settings）。验证方式：在设置中点击「Preview」预览模板效果，并用 Ctrl+J（Windows）/ Cmd+J（macOS）手动触发 Live Template。

Answer 1

```html

一、现象确认与基础验证（What & When）

首先需明确问题发生的具体场景：是新建 .java 文件时 File Header 未插入？还是在编辑器中键入 main 后按 <kbd>Tab</kbd> 无响应？二者机制不同——前者由 File and Code Templates 驱动，后者依赖 Live Templates 引擎。务必区分触发时机：File Header 仅在 文件系统层面创建新文件时（如右键 → New → Java Class）注入；而 Live Template 是编辑时的实时代码补全行为。

二、作用域与启用状态校验（Where & Whether）

• File Header 模板：进入 Settings → Editor → File and Code Templates → Files，检查目标模板（如 Class）是否已启用，且「Enable live templates」未被误关（该选项影响所有模板解析）。
• Live Template：在 Settings → Editor → Live Templates 中定位对应缩写（如 main），确认右侧开关为 ON，且「Applicable in」至少勾选 Java 或 Kotlin（支持多选，但不可仅选 Everywhere——它不覆盖语法上下文约束）。

三、变量合法性与上下文兼容性（How & Why）

IntelliJ 官方支持的预定义变量有限，常见有效变量包括：$USER$、$DATE$、$TIME$、$YEAR$、$MONTH$、$DAY$、$HOUR$、$MINUTE$。而 $TIME_STAMP$、$AUTHOR$（非标准）、$PROJECT_NAME$（仅部分模板支持）等属于无效或已弃用变量，会导致模板解析失败静默降级。可通过点击设置页右下角「Preview」按钮实时渲染验证变量有效性：

/**  
 * @author $USER$  
 * @date $DATE$ $TIME$  
 * @version 1.0  
 */

四、配置层级与项目隔离性分析（Scope & Sync）

配置类型	路径	影响范围	同步要点
Default Settings	IDE Settings → Editor → …	所有新项目继承	修改后需重启 IDE 或通过 File → Manage IDE Settings → Sync 手动推送
Project Settings	Project Settings → Editor → …	仅当前项目生效	检查 .idea/misc.xml 中 <component name="ProjectRootManager"> 是否覆盖了模板路径

五、插件冲突与缓存诊断（External Interference）

某些高侵入性插件（如 Rainbow Brackets 6.27+、CodeGlance 3.1.2）会劫持编辑器事件链，导致 Live Template 的 Tab 触发逻辑被拦截。诊断步骤：

1. 临时禁用所有第三方插件（Settings → Plugins → 取消勾选非 JetBrains 官方插件）
2. 执行 File → Invalidate Caches and Restart → Invalidate and Restart
3. 使用快捷键 <kbd>Ctrl+J</kbd>（Windows/Linux）或 <kbd>Cmd+J</kbd>（macOS）强制调出模板选择面板，观察是否可见目标模板

六、深度调试：启用模板日志与事件追踪

对资深开发者，可开启 IntelliJ 内部模板调试日志：

1. Help → Diagnostic Tools → Debug Log Settings
2. 添加日志规则：#com.intellij.codeInsight.template.impl.TemplateManagerImpl 和 #com.intellij.codeInsight.template.impl.LiveTemplateLookupElement
3. 复现问题后，在 Help → Show Log in Explorer 中搜索 "template resolved" 或 "applicable context: false" 关键字

若日志中出现 context does not match，说明当前光标位置的 PSI 元素（如 PsiJavaFile vs PsiClass）未满足模板声明的 Applicable in 条件。

七、进阶方案：自定义变量与 Groovy 脚本扩展

当标准变量无法满足需求（如自动提取 Git author、模块名、包路径），可利用 Groovy 脚本扩展：

// 在 Live Template 编辑页点击 "Edit variables"
// 为 $MODULE_NAME$ 定义脚本：
groovyScript("return _project.getName()")

// 为 $GIT_AUTHOR$ 定义（需安装 Git 插件）：
groovyScript("return com.intellij.openapi.vcs.VcsDataKeys.VCS_DATA_KEY.getData(_editor.getDataContext())?.getVcsRoot().getVcs().getName() ?: 'unknown'")

注意：Groovy 脚本执行受沙箱限制，禁止 I/O 和反射调用，且需在 Settings → Advanced Settings → Enable custom template scripts 中显式开启。

八、自动化验证流程图（Mermaid）

graph TD
  A[触发失败] --> B{是新建文件？}
  B -->|Yes| C[检查 File and Code Templates]
  B -->|No| D[检查 Live Templates]
  C --> E[确认模板启用 & 文件类型匹配]
  D --> F[确认缩写存在 & Applicable in 勾选]
  E --> G[验证变量有效性 Preview]
  F --> G
  G --> H{Preview 正常？}
  H -->|Yes| I[检查插件/缓存]
  H -->|No| J[修正变量或脚本]
  I --> K[禁用插件 → Invalidate Caches]
  K --> L[重新测试 Ctrl+J]

```