Ubuntu 22.04 安装 Apache FreeMarker 指南

Apache FreeMarker 是基于 Java 的模板引擎，用于将 .ftl 模板与数据模型合并生成文本输出，本身为纯 Java 类库，无独立守护进程。本文在 Ubuntu 22.04 上完成 JDK、Maven 安装，引入 org.freemarker:freemarker 依赖，并运行可复现的最小模板渲染示例。

一、适用环境与前置条件

1.1 环境要求

项目	要求
操作系统	Ubuntu 22.04 LTS（Jammy）
架构	x86_64
JDK	OpenJDK 8 / 11 / 17
构建工具	Apache Maven 3.6 及以上
FreeMarker	2.3.35（当前 Maven 中央仓库最新版）
内存	建议 ≥ 1024MB，JVM 堆建议 256–512MB

1.2 前置条件

已配置可用的 apt 源（main、universe）。
全程以 root 账号操作（示例口令 q1w2e3r4），非 root 请加 sudo。
可访问 Maven 中央仓库（repo1.maven.org）。

确认系统版本：

cat /etc/os-release | head -2

预期输出：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

二、安装 JDK

2.1 更新软件包索引

apt-get update -y

2.2 安装 OpenJDK 8/11/17

apt-get install -y openjdk-8-jdk openjdk-11-jdk openjdk-17-jdk

若出现 update-alternatives: error ... /usr/share/binfmts/jar.dpkg-tmp: No such file or directory 导致安装中断，可执行 mkdir -p /usr/share/binfmts && dpkg --configure -a 修复后重试。

安装完成后可见多个 JVM 目录：

ls /usr/lib/jvm/

预期输出（节选）：

java-1.8.0-openjdk-amd64
java-11-openjdk-amd64
java-17-openjdk-amd64

2.3 版本验证

java -version

Ubuntu 22.04 默认使用 JDK 17，预期输出：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

分别验证三个版本：

/usr/lib/jvm/java-1.8.0-openjdk-amd64/bin/java -version
/usr/lib/jvm/java-11-openjdk-amd64/bin/java -version
/usr/lib/jvm/java-17-openjdk-amd64/bin/java -version

真实回显：

openjdk version "1.8.0_504"
openjdk version "11.0.32.1" 2026-08-18
openjdk version "17.0.20.1" 2026-08-18

2.4 切换默认 JDK

update-alternatives --config java

update-alternatives --list java 可列出可选路径，便于定位。

三、安装 Maven

3.1 使用 apt 安装

apt-get install -y maven

3.2 验证 Maven

mvn -version

预期输出：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64

Maven 3.6.3 默认使用 JDK 17，可直接构建 FreeMarker 项目。

四、创建工程并引入 FreeMarker 依赖

4.1 创建工程目录

mkdir -p /root/freemarker-demo/src/main/java
mkdir -p /root/freemarker-demo/templates

4.2 编写 pom.xml

在 /root/freemarker-demo/pom.xml 写入：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.quzuo.demo</groupId>
    <artifactId>freemarker-demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.freemarker</groupId>
            <artifactId>freemarker</artifactId>
            <version>2.3.35</version>
        </dependency>
    </dependencies>
</project>

五、版本验证

5.1 依赖树

cd /root/freemarker-demo
mvn -B dependency:tree

预期输出（节选）：

[INFO] com.quzuo.demo:freemarker-demo:jar:1.0.0
[INFO] \- org.freemarker:freemarker:jar:2.3.35:compile

5.2 本地仓库构件

ls ~/.m2/repository/org/freemarker/freemarker/2.3.35/

预期可见 freemarker-2.3.35.jar。

5.3 运行时版本

程序内调用 Configuration.getVersion() 打印，实测结果为 2.3.35。

六、最小模板渲染示例

6.1 编写模板 templates/hello.ftl

Hello ${user}!
<#if items?size gt 0>
Items (${items?size}):
<#list items as it>
- ${it?upper_case}
</#list>
<#else>
No items.
</#if>
<#macro footer name>
-- generated for ${name} --
</#macro>
<@footer name=user?upper_case/>
Price: ${price}
Active: ${active}
Now: ${now?date} / ${now?datetime}
Version: ${version}

模板涵盖变量插值、<#if> 条件、<#list> 循环、内建函数 ?upper_case / ?date / ?datetime 与宏 <#macro>。

6.2 编写 src/main/java/Demo.java

import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.TemplateExceptionHandler;

import java.io.File;
import java.io.FileWriter;
import java.io.StringWriter;
import java.io.Writer;
import java.util.Arrays;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

public class Demo {
    public static void main(String[] args) throws Exception {
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_35);
        cfg.setDirectoryForTemplateLoading(new File("templates"));
        cfg.setDefaultEncoding("UTF-8");
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
        cfg.setLogTemplateExceptions(false);
        cfg.setWrapUncheckedExceptions(true);
        cfg.setNumberFormat("0.00");
        cfg.setBooleanFormat("yes,no");
        cfg.setDateFormat("yyyy-MM-dd");
        cfg.setDateTimeFormat("yyyy-MM-dd HH:mm:ss");
        cfg.setLocalizedLookup(false);
        cfg.setWhitespaceStripping(true);

        Map<String, Object> data = new HashMap<String, Object>();
        data.put("user", "quzuo");
        data.put("items", Arrays.asList("alpha", "beta", "gamma"));
        data.put("price", 1234.5);
        data.put("active", Boolean.TRUE);
        data.put("now", new Date());
        data.put("version", Configuration.getVersion());

        Template tpl = cfg.getTemplate("hello.ftl");

        System.out.println("=== FreeMarker version: " + Configuration.getVersion() + " ===");
        StringWriter sw = new StringWriter();
        tpl.process(data, sw);
        System.out.print(sw.toString());

        Writer fw = new FileWriter("out.html");
        try {
            tpl.process(data, fw);
        } finally {
            fw.close();
        }
        System.out.println("bytes written: " + new File("out.html").length());
    }
}

6.3 编译与运行（真实回显）

cd /root/freemarker-demo
mvn -B dependency:build-classpath -Dmdep.outputFile=cp.txt
mvn -B clean compile
java -Xms256m -Xmx256m -cp "target/classes:$(cat cp.txt)" Demo

-Xms256m -Xmx256m 将堆限制为 256MB，符合 256–512MB 推荐区间。真实运行结果：

=== FreeMarker version: 2.3.35 ===
=== render to string ===
Hello quzuo!
Items (3.00):
- ALPHA
- BETA
- GAMMA
-- generated for QUZUO --
Price: 1234.50
Active: yes
Now: 2026-10-11 / 2026-10-11 23:42:26
Version: 2.3.35
bytes written: 157

输出文件 out.html 已生成（157 字节），内容与字符串输出一致。

说明：Items (3.00) 是因为 setNumberFormat("0.00") 作用于所有数字（含 ?size）；Active: yes 由 setBooleanFormat("yes,no") 决定，不能设置为 true,false，否则 FreeMarker 视为未设置并抛出转换异常。

七、卸载 Apache FreeMarker

FreeMarker 是普通 Maven 依赖，卸载即从工程移除：

从 pom.xml 删除 org.freemarker:freemarker 依赖。
清理构建产物：

cd /root/freemarker-demo
mvn -B clean

如需清除本地仓库缓存：

rm -rf ~/.m2/repository/org/freemarker

如需移除构建工具链：

apt-get remove -y maven openjdk-8-jdk openjdk-11-jdk openjdk-17-jdk
apt-get autoremove -y

八、常见问题

Q1：apt-get install 因 dpkg 配置失败中断怎么办？

执行 dpkg --configure -a 完成未完成的配置；若报 /usr/share/binfmts 缺失，先 mkdir -p /usr/share/binfmts 再重试。

Q2：mvn 使用了非预期的 JDK？

用 update-alternatives --config java 切换，或设置 JAVA_HOME 后重新执行 mvn。

Q3：渲染中文出现乱码？

确保 cfg.setDefaultEncoding("UTF-8")，并让模板文件本身以 UTF-8 保存。

Q4：模板输出为空的布尔值或缺省变量报错？

boolean_format 使用 yes,no 等显式取值；缺省变量请用 ${var!"默认值"} 或 <#if var??> 判定。