# 模板语言：Velocity 和 FreeMarker

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

IntelliJ IDEA 让您在 [Velocity](https://velocity.apache.org)（VTL）和 [FreeMarker](https://freemarker.apache.org/)（FTL）中开发模板。

Procedure: 安装 Apache Velocity 和 FreeMarker 插件

此功能性依赖于 [Apache Velocity](https://plugins.jetbrains.com/plugin/21738-apache-velocity) 和 [FreeMarker](https://plugins.jetbrains.com/plugin/27369-freemarker) 插件，需要安装并启用这些插件。

> **Note:**
> 如果没有 Ultimate 订阅，这些插件在 IntelliJ IDEA 中不可用。

1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择  `插件` 。

2. 找到  Apache Velocity  和  FreeMarker  插件，然后点击每个插件旁边的   安装  。

3. 如果出现提示，请重启 IDE。

![模板语言指令自动完成](https://resources.jetbrains.com.cn/help/img/idea/2026.3/velocity_code_completion_1.png)

![模板语言变量补全](https://resources.jetbrains.com.cn/help/img/idea/2026.3/velocity_code_completion_2.png)

默认支持以下文件类型：

|  VTL  |   `.ft` ,  `.vm` ,  `.vsl`   |
|  FTL  |   `.ftl` ,  `.ftlh` ,  `.ftlx`   |

要启用模板静态部分编写的语言的代码辅助（这些语言称为  模板数据语言 ），请执行以下操作之一：

Procedure: 将模板数据语言与项目中的文件和文件夹关联

1. 在   设置   对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))）中，点击   语言与框架  ，然后点击   模板数据语言  。

2. 点击项目或相应目录或文件右侧的模板数据语言单元格，然后选择语言。

3. 点击   OK   以应用更改。

可以直接在编辑器中使用   将模板数据语言更改为   上下文菜单命令为单个模板文件分配模板数据语言。

Procedure: 为相应的文件类型添加扩展模式

1. 在   设置   对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))）中，点击   编辑器  ，然后点击   文件类型  。

2. 在   识别的文件类型   下，选择   FreeMarker 模板   或   Velocity 模板  。

3. 在   文件名模式   下，点击 ![](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.expui.general.add.svg)。

4. 在   添加通配符  对话框中，指定文件名扩展模式，选择一种语言，然后点击   OK  。

![velocity_add_pattern](https://resources.jetbrains.com.cn/help/img/idea/2026.3/velocity_add_pattern.png)

5. 点击   OK   以应用更改。

## 修复未解析的引用

IntelliJ IDEA 提供用于检测模板语言中未解决引用的 [检查](code-inspection.html)：

![未解析引用的示例模板语言检查](https://resources.jetbrains.com.cn/help/img/idea/2026.3/velocity_inspection.png)

未解析的引用可以通过使用 [intention actions](intention-actions.html)来修复。 您可以选择在同一个文件中添加注释，或者创建一个单独的文件来存放注释。 更多信息请参阅 [Special comments](#special-comments)。

![修复未解析引用的示例模板语言用途](https://resources.jetbrains.com.cn/help/img/idea/2026.3/velocity_intention.png)

> **Note:**
> 此类情况下的注释用于提供有关引用的缺失信息。

在后者的情况下，将创建一个默认名称为  `velocity_implicit.vm`  或  `freemarker_implicit.ftl`  的文件。 此文件以以下注释开头：

```
#* @implicitly included *#
```

注释文件中提供了定义引用类型的代码补全功能。

如果您重命名文件或将其移动到源根目录内的不同位置，引用定义将不会丢失。

## 特殊注释

IntelliJ IDEA 提供了以下用于模板语言的特殊注释：

FreeMarker:

FreeMarker 注释使用  `<#--`  和  `-->`  或  `[#--`  和  `--#]`  进行分隔。

|  注释  |  描述  |
| --- | --- |
|   `@implicitly included`   |  任何以该注释开头的 FreeMarker 文件都会包含在同一模块或其依赖项中的所有文件中。 使用此类专用注释文件来定义 IDE 特定的注释，以免污染模板文件。  |
|   `@ftlvariable`   |  定义变量。 例如，以下注释声明了一个名称为  `foo` 、类型为  `字符串`  的变量，仅在指定文件中可见：    ``` <#-- @ftlvariable name="foo" type="java.lang.String" file="path/to/file" --> ```  要在这种情况下正确解析  `字符串` ，模块应已附加 JDK。 支持基本类型和泛型类型。  `file`  参数是可选的。     `@ftlvariable`  注释也可以使用  `name=""` （空字符串）。 在这种情况下，指定类型被视为根数据模型，其所有成员都可作为变量使用。     |
|   `@ftlroot`   |  定义了相对于其解析  `import` 和  `包括` 指令的路径。 路径是相对于当前 FTL 文件包中的任何目录指定的。 JAR 文件内的路径也支持，例如：    ``` <#-- @ftlroot "path/to.jar!/path/inside/jar" --> ```    |

Velocity:

Velocity 注释使用  `#*`  和  `*#`  进行分隔。

|  注释  |  描述  |
| --- | --- |
|   `@implicitly included`   |  任何以此注释开头的 Velocity 文件将包含在同一模块中的所有文件中。 使用此类专用注释文件来定义 IDE 特定的注释，以免污染模板文件。  |
|   `@vtlvariable`   |  定义变量。 例如，以下注释声明了一个名称为  `foo` 、类型为  `字符串`  的变量，仅在指定文件中可见：    ``` #* @vtlvariable name="foo" type="java.lang.String" file="path/to/file" *# ```  要在这种情况下正确解析  `字符串` ，模块应已附加 JDK。 支持基本类型和泛型类型。  `file`  参数是可选的。  |
|   `@vtlmacrolibrary`   |  定义与此注释文件相关的模板宏文件。 例如，以下注释使  `lib.vm`  的宏在  `file.vm`  中可用于代码洞察：    ``` #* @vtlmacrolibrary path="lib.vm" file="file.vm" *# ```    |
|   `@velocityproperties`   |  定义  `velocity.properties`  文件和运行时相对于带有此注释的文件的根目录。 例如：    ``` #* @velocityproperties path=”path/to/velocity.properties” runtime_root=”path/to/runtime/root/dir” *# ```    |

