CentOS 8 安装 Apache Velocity 指南

在 CentOS 8 服务器上从零集成 Apache Velocity 2.4.1：安装 OpenJDK 17 与 Maven，修正 maven.conf 指向，创建工程引入依赖完成渲染验证，附 JVM 堆限定、实测回显与卸载步骤。

Apache VelocityApache Velocity2026/10/12

CentOS 8 安装 Apache Velocity 指南

一、环境信息

项目值
操作系统CentOS Linux 8
内核6.8.0-138-generic
配置12 vCPU / 32GiB 内存
登录账号root
JDKOpenJDK 17.0.1（java-17-openjdk-devel）
构建工具Apache Maven 3.5.4（dnf 仓库版）
组件Apache Velocity（velocity-engine-core）2.4.1
网络可直连 Maven Central（repo.maven.apache.org）

Apache Velocity 是纯 Java 模板引擎类库，以 jar 包形态被应用引入，没有独立守护进程，无需开放监听端口，全部验证通过编译和运行 Java 程序完成。

二、前置条件

  1. 服务器可联网，能访问 Maven Central 仓库。
  2. 已获取 root 权限，可执行 dnf 安装与系统文件修改。
  3. dnf 软件源可用（AppStream 仓库提供 maven 与 java-17-openjdk-devel）。

确认软件源中候选版本：

dnf -q list maven java-17-openjdk-devel

实测回显：

Available Packages
java-17-openjdk-devel.x86_64   1:17.0.1.0.12-2.el8_5                   AppStream
maven.noarch                   1:3.5.4-5.module_el8.0.0+39+6a9b6e22    AppStream

三、版本选型说明

组件选定版本说明
velocity-engine-core2.4.1Maven Central 当前最新稳定版（2.x 系列），2.x 为官方维护主线
JDKOpenJDK 172.4.1 要求 Java 8 及以上，选 17 LTS 兼容性最好
Maven3.5.4dnf 官方源自带版本，可正常编译 JDK 17 工程
slf4j-simple1.7.36velocity-engine-core 2.4.1 依赖 slf4j-api 1.7.36，需配套绑定
velocity-tools-generic3.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

dnf install -y java-17-openjdk-devel maven

安装完成后检查当前默认 Java 版本：

java -version

实测回显（该机预装了 Java 8，默认仍指向旧版本）：

openjdk version "1.8.0_312"
OpenJDK Runtime Environment (build 1.8.0_312-b07)
OpenJDK 64-Bit Server VM (build 25.312-b07, mixed mode, sharing)

4.2 切换系统默认 Java 到 17

将 java 与 javac 的 alternatives 指向 17：

alternatives --set java java-17-openjdk.x86_64

alternatives --set javac java-17-openjdk.x86_64

再让 Maven 使用 17。RHEL 版 /usr/bin/mvn 会读取 /etc/java/maven.conf 中的 JAVA_HOME，实测该文件默认不存在、Maven 回落到 Java 8，需显式写入：

echo 'JAVA_HOME=/usr/lib/jvm/java-17-openjdk' > /etc/java/maven.conf

验证：

mvn -version

实测回显：

Apache Maven 3.5.4 (Red Hat 3.5.4-5)
Maven home: /usr/share/maven
Java version: 17.0.1, vendor: Red Hat, Inc., runtime: /usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64
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.3 创建 Maven 工程

mkdir -p /root/velocity-quickstart/src/main/java/com/example

mkdir -p /root/velocity-quickstart/src/main/resources/templates

4.4 编写 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.5 编写主类与模板

创建 /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.6 固定 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.7 编译工程

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.8 运行渲染示例

cd /root/velocity-quickstart && LANG=C.UTF-8 mvn -q exec:java -Dexec.mainClass=com.example.App

实测回显：

欢迎来到 quzuo.net！
模块列表：
- 技术专栏
- 文档发布
- 归档中心
共 3 个模块。

4.9 限定 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.8 一致，渲染正常。

堆参数修改位置：修改 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.10 验证结果核对

  • mvn -version 显示 Java version: 17.0.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/-XmxJVM 堆下限与上限，承载 Velocity 的应用按 256 至 512MB 起步
/etc/java/maven.confMaven 使用的 JAVA_HOME，本篇指向 /usr/lib/jvm/java-17-openjdk
/etc/profile.d/lang.sh会话 locale，保证中文输出正常

六、注意事项

  1. velocity-engine-core 2.4.1 硬依赖 slf4j-api：classpath 完全没有 slf4j-api 时，创建引擎直接抛 NoClassDefFoundError: org/slf4j/LoggerFactory；只有 api 没有绑定时日志被吞。务必保留 slf4j-simple。
  2. 不要用旧坐标 org.apache.velocity:velocity-tools:2.0 搭配 2.4.1，那是面向 Velocity 1.7 的旧包；2.x 配套应使用 org.apache.velocity.tools:velocity-tools-generic:3.1。
  3. 修改 src/main/resources 下模板后需重新 mvn compile，否则运行时读到的仍是 target/classes 里的旧副本。
  4. MAVEN_OPTS 与 pom 插件 jvmArgs 的差异见 4.9，堆参数务必用可验证的方式设置并复查。
  5. 升级 2.x 小版本时关注弃用告警，例如 input.encoding 已由 resource.default_encoding 取代，日志会打印 WARN 提示新键名。

七、常见问题

Q1：mvn clean compile 报 Fatal error compiling: invalid target release: 17 怎么办？ A：Maven 实际运行在旧 JDK 上。执行 mvn -version 查看 Java version；若为 1.8，按 4.2 节写 /etc/java/maven.conf 并切换 alternatives 后重试。实测修正后回显 Java version: 17.0.1，编译通过。

Q2：程序输出的中文全部变成问号如何处理？ A：系统 locale 为 POSIX 所致。按 4.6 节设置 LANG=C.UTF-8，或在 java 命令前临时加 LANG=C.UTF-8。实测 ANSI_X3.4-1968 环境下输出问号，切换后中文完整。

Q3：启动时打印 SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder" 是什么问题？ A：说明 classpath 只有 slf4j-api 没有绑定，Velocity 日志会全部被丢弃。在 pom 中加入 org.slf4j:slf4j-simple:1.7.36 后告警消失，日志正常输出到标准错误流。

八、卸载方式

移除项目文件与本地仓库缓存：

rm -rf /root/velocity-quickstart

rm -rf /root/.m2/repository/org/apache/velocity

移除 Maven 与 JDK 17 软件包：

dnf remove -y maven java-17-openjdk-devel

清理本篇修改过的系统配置：

rm -f /etc/java/maven.conf /etc/profile.d/lang.sh

alternatives --auto java

alternatives --auto javac

九、参考链接

  1. Apache Velocity 官方主页：https://velocity.apache.org/
  2. velocity-engine-core 2.4.1（Maven Central）：https://mvnrepository.com/artifact/org.apache.velocity/velocity-engine-core
  3. Velocity 引擎开发者文档：https://velocity.apache.org/engine/2.4/developer-guide.html
  4. VTL 参考指南：https://velocity.apache.org/engine/2.4/vtl-reference.html