Ubuntu 22.04 安装 Apache Velocity 指南
在 Ubuntu 22.04 服务器上从零集成 Apache Velocity 2.4.1：apt 安装 OpenJDK 17 与 Maven 3.6.3，创建工程引入依赖并渲染验证，限定 JVM 堆内存范围，附完整实测回显与卸载清理步骤。
Apache VelocityApache Velocity2026/10/12
Ubuntu 22.04 安装 Apache Velocity 指南
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| 内核 | 6.8.0-138-generic |
| 配置 | 12 vCPU / 32GiB 内存 |
| 登录账号 | root |
| JDK | OpenJDK 17.0.20.1（openjdk-17-jdk） |
| 构建工具 | Apache Maven 3.6.3（apt 仓库版） |
| 组件 | Apache Velocity（velocity-engine-core）2.4.1 |
| 网络 | 可直连 Maven Central（repo.maven.apache.org） |
Apache Velocity 是纯 Java 模板引擎类库，以 jar 包形态被应用引入，没有独立守护进程，无需开放监听端口，全部验证通过编译和运行 Java 程序完成。
二、前置条件
- 服务器可联网，能访问 Maven Central 仓库与 Ubuntu 软件源。
- 已获取 root 权限，可执行 apt 安装。
- apt 软件源可用。
刷新索引并确认候选版本：
apt-get update -qq
apt-cache policy maven openjdk-17-jdk | grep -E 'maven:|openjdk-17-jdk:|Candidate'
实测回显：
maven:
Candidate: 3.6.3-5
openjdk-17-jdk:
Candidate: 17.0.20.1+1-1~22.04
三、版本选型说明
| 组件 | 选定版本 | 说明 |
|---|---|---|
| velocity-engine-core | 2.4.1 | Maven Central 当前最新稳定版（2.x 系列），2.x 为官方维护主线 |
| JDK | OpenJDK 17 | 2.4.1 要求 Java 8 及以上，选 17 LTS 兼容性最好 |
| Maven | 3.6.3 | Ubuntu 22.04 官方源自带版本，可正常编译 JDK 17 工程 |
| slf4j-simple | 1.7.36 | velocity-engine-core 2.4.1 依赖 slf4j-api 1.7.36，需配套绑定 |
| velocity-tools-generic | 3.1 | 可选工具箱，泛用工具（日期、数学、转义）配套版本 |
版本确认命令（在本机任一可联网环境查询 Maven Central 元数据）：
curl -s https://repo1.maven.org/maven2/org/apache/velocity/velocity-engine-core/maven-metadata.xml | grep -E '<latest>|<release>'
实测回显：
<latest>2.4.1</latest>
<release>2.4.1</release>
四、部署步骤
4.1 安装 JDK 17 与 Maven
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk maven
安装完成后验证版本：
java -version
实测回显：
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)
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
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"
回显中 platform encoding 为 ANSI_X3.4-1968（POSIX locale），会导致控制台输出中文乱码，处理方式见 4.6。
4.2 创建 Maven 工程
mkdir -p /root/velocity-quickstart/src/main/java/com/example
mkdir -p /root/velocity-quickstart/src/main/resources/templates
4.3 编写 pom.xml 引入依赖
创建 /root/velocity-quickstart/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.example</groupId>
<artifactId>velocity-quickstart</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>2.4.1</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.7.36</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.1.0</version>
</plugin>
</plugins>
</build>
</project>
依赖说明：velocity-engine-core 2.4.1 会传递引入 commons-lang3 3.17.0 与 slf4j-api 1.7.36；slf4j-simple 是日志绑定，缺少它时 Velocity 的全部日志会被 SLF4J 空实现吞掉并在启动时打印告警。
4.4 编写主类与模板
创建 /root/velocity-quickstart/src/main/java/com/example/App.java：
package com.example;
import org.apache.velocity.Template;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.VelocityEngine;
import java.io.StringWriter;
import java.util.Arrays;
public class App {
public static void main(String[] args) {
VelocityEngine engine = new VelocityEngine();
engine.setProperty("resource.loaders", "classpath");
engine.setProperty("resource.loader.classpath.class",
"org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader");
engine.setProperty("resource.default_encoding", "UTF-8");
engine.init();
VelocityContext context = new VelocityContext();
context.put("product", "quzuo.net");
context.put("modules", Arrays.asList("技术专栏", "文档发布", "归档中心"));
Template template = engine.getTemplate("templates/hello.vm", "UTF-8");
StringWriter writer = new StringWriter();
template.merge(context, writer);
System.out.println(writer);
}
}
创建 /root/velocity-quickstart/src/main/resources/templates/hello.vm：
欢迎来到 $product！
模块列表：
#foreach($m in $modules)
- $m
#end
共 $modules.size() 个模块。
4.5 固定 UTF-8 运行环境
本机默认 locale 为 POSIX，JVM 的 file.encoding 实测为 ANSI_X3.4-1968，直接运行会输出问号乱码。写入 profile 使登录会话默认 UTF-8：
echo 'export LANG=C.UTF-8' > /etc/profile.d/lang.sh
source /etc/profile.d/lang.sh
实测对照（同一台机器切换前后）：
LANG 未设置：file.encoding = ANSI_X3.4-1968 / native.encoding = ANSI_X3.4-1968
LANG=C.UTF-8：file.encoding = UTF-8 / native.encoding = UTF-8
4.6 编译工程
cd /root/velocity-quickstart && mvn clean compile
实测回显（节选）：
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.292 s
[INFO] Finished at: 2026-10-12T09:43:53Z
[INFO] ------------------------------------------------------------------------
4.7 运行渲染示例
cd /root/velocity-quickstart && LANG=C.UTF-8 mvn -q exec:java -Dexec.mainClass=com.example.App
实测回显：
欢迎来到 quzuo.net！
模块列表：
- 技术专栏
- 文档发布
- 归档中心
共 3 个模块。
4.8 限定 JVM 堆内存并以 jar 方式运行
Velocity 本身不占常驻内存，但承载它的应用 JVM 应设置堆上下限，推荐 256 至 512MB 起步。打包后以 java 直接运行，堆参数直接跟在 java 命令上：
cd /root/velocity-quickstart && mvn -q package -DskipTests
cd /root/velocity-quickstart && mvn -q dependency:copy-dependencies -DoutputDirectory=libs
cd /root/velocity-quickstart && LANG=C.UTF-8 java -Xms256m -Xmx512m -cp 'target/velocity-quickstart-1.0.0.jar:libs/*' com.example.App
实测回显与 4.7 一致，渲染正常。
堆参数修改位置：修改 java 命令后的 -Xms256m 与 -Xmx512m 两个值即可；若通过 mvn exec:java 运行，需用 MAVEN_OPTS 环境变量传递，例如 MAVEN_OPTS='-Xms256m -Xmx512m'，因为 exec:java 在 Maven 自身 JVM 内执行，pom 中插件的 jvmArgs 参数对它无效。
堆参数验证（三种方式实测）：
java -Xms256m -Xmx512m -XshowSettings:vm -version
实测回显：
VM settings:
Min. Heap Size: 256.00M
Max. Heap Size: 512.00M
Using VM: OpenJDK 64-Bit Server VM
java -Xms256m -Xmx512m -XX:+PrintFlagsFinal -version | grep -i maxheapsize
实测回显：
size_t MaxHeapSize = 536870912 {product} {command line}
size_t SoftMaxHeapSize = 536870912 {manageable} {ergonomic}
程序运行期间用 jps 与 ps 采集实测回显：
jps -lv：
6914 com.example.VelocityDemo -Xms256m -Xmx512m
ps -ef：
root 6914 6853 13 09:27 ? 00:00:00 java -Xms256m -Xmx512m -cp target/classes:libs/* com.example.VelocityDemo --hold
4.9 验证结果核对
mvn -version显示 Java version: 17.0.20.1。ls target/classes/com/example下存在 App.class。ls target/classes/templates下存在 hello.vm。- 运行回显出现完整中文渲染结果且无问号乱码。
- 依赖树确认版本：
cd /root/velocity-quickstart && mvn dependency:tree | grep velocity
实测回显：
[INFO] +- org.apache.velocity:velocity-engine-core:jar:2.4.1:compile
五、配置说明
| 位置 | 作用 |
|---|---|
| pom.xml dependencies | 引入 velocity-engine-core 与 slf4j-simple，版本在此维护 |
| pom.xml maven.compiler.source/target | 编译目标版本，当前 17 |
| 代码 setProperty | 引擎级配置，本篇用 resource.loaders、resource.loader.classpath.class、resource.default_encoding 三项 |
| java 命令 -Xms/-Xmx | JVM 堆下限与上限，承载 Velocity 的应用按 256 至 512MB 起步 |
| /etc/profile.d/lang.sh | 会话 locale，保证中文输出正常 |
六、注意事项
- velocity-engine-core 2.4.1 硬依赖 slf4j-api：classpath 完全没有 slf4j-api 时，创建引擎直接抛 NoClassDefFoundError: org/slf4j/LoggerFactory；只有 api 没有绑定时日志被吞。务必保留 slf4j-simple。
- 不要用旧坐标 org.apache.velocity:velocity-tools:2.0 搭配 2.4.1，那是面向 Velocity 1.7 的旧包；2.x 配套应使用 org.apache.velocity.tools:velocity-tools-generic:3.1。
- 修改 src/main/resources 下模板后需重新 mvn compile，否则运行时读到的仍是 target/classes 里的旧副本。
- MAVEN_OPTS 与 pom 插件 jvmArgs 的差异见 4.8，堆参数务必用可验证的方式设置并复查。
- 升级 2.x 小版本时关注弃用告警，例如 input.encoding 已由 resource.default_encoding 取代，日志会打印 WARN 提示新键名。
七、常见问题
Q1：运行后中文输出全是问号如何处理？
A：Ubuntu 22.04 最小环境默认 locale 为 POSIX，JVM 的 file.encoding 实测为 ANSI_X3.4-1968。按 4.5 节设置 LANG=C.UTF-8，或在 java、mvn 命令前临时加 LANG=C.UTF-8，切换后中文渲染完整。
Q2：启动时打印 SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder" 是什么问题？ A：说明 classpath 只有 slf4j-api 没有绑定，Velocity 日志会全部被丢弃。在 pom 中加入 org.slf4j:slf4j-simple:1.7.36 后告警消失，日志正常输出到标准错误流。
Q3：mvn exec:java 配置了 jvmArgs 但程序实际堆内存没变是为什么？ A：exec:java 在 Maven 自身的 JVM 进程内执行，插件 jvmArgs 对它无效。实测默认运行时程序读取 maxMemory 为 8016 MB，改用 MAVEN_OPTS 传入 -Xms256m -Xmx512m 后实测 maxMemory 为 512 MB；或改用 java -cp 直接运行并在命令行携带堆参数。
八、卸载方式
移除项目文件与本地仓库缓存：
rm -rf /root/velocity-quickstart
rm -rf /root/.m2/repository/org/apache/velocity
移除 Maven 与 JDK 17 软件包：
apt-get remove --purge -y maven openjdk-17-jdk
apt-get autoremove -y
清理本篇修改过的系统配置：
rm -f /etc/profile.d/lang.sh
九、参考链接
- Apache Velocity 官方主页：https://velocity.apache.org/
- velocity-engine-core 2.4.1（Maven Central）：https://mvnrepository.com/artifact/org.apache.velocity/velocity-engine-core
- Velocity 引擎开发者文档：https://velocity.apache.org/engine/2.4/developer-guide.html
- VTL 参考指南：https://velocity.apache.org/engine/2.4/vtl-reference.html
章节目录