Log4j2 是目前 Java 项目中应用非常广泛的日志框架之一，其中 RollingFileAppender 负责实现日志文件滚动功能，可以根据文件大小、时间周期等规则自动创建新的日志文件。在实际项目配置过程中，Filename Pattern（文件名匹配模式）相关错误十分常见，例如日志无法正常归档、文件名格式异常、启动时报配置错误等问题。

RollingFileAppender 的 Filename Pattern 配置看似简单，但它涉及文件路径、日期格式、压缩规则、变量解析等多个机制。理解其工作原理，可以快速定位并解决日志滚动异常。

Log4j2 RollingFileAppender Filename Pattern 基本原理

RollingFileAppender 主要由以下几个部分组成：

• fileName：当前正在写入的日志文件路径。

• filePattern：滚动后的历史日志文件名称规则。

• Policies：触发日志滚动的策略。

• Strategy：滚动文件保留策略。

一个典型配置如下：

XML

     name="RollingFile"
                 fileName="/logs/app.log"
                 filePattern="/logs/app-%d{yyyy-MM-dd}-%i.log.gz">
        
            %d{yyyy-MM-dd HH:mm:ss} %-5p %c{1} - %m%n
        

        
             />
             size="100 MB"/>
        

         max="30"/>
    

其中：

XML
filePattern="/logs/app-%d{yyyy-MM-dd}-%i.log.gz"

表示：

• %d{yyyy-MM-dd}：按照日期生成文件名。

• %i：按照编号递增生成文件。

• .gz：表示滚动文件自动压缩。

例如：

app-2026-10-02-1.log.gz
app-2026-10-02-2.log.gz

---

常见 Filename Pattern 错误类型

1. 日期格式写法错误

日期占位符是 Filename Pattern 中最容易出错的地方。

错误示例：

XML
filePattern="/logs/app-%d{YYYY-MM-DD}.log"

很多开发人员习惯使用大写：

YYYY
DD

但 Java 日期格式中：

• yyyy 表示年份。

• YYYY 表示周年份。

• dd 表示月份中的日期。

• DD 表示一年中的第几天。

因此：

错误：

XML
%d{YYYY-MM-DD}

正确：

XML
%d{yyyy-MM-dd}

如果使用错误格式，可能导致跨年时日志文件名称异常。

例如：

app-2026-01-01.log

可能被解析成上一年的周年份。

---

2. 缺少日期转换格式

部分配置直接写：

XML
filePattern="/logs/app-%d.log"

虽然 Log4j2 可以识别，但日期格式由默认规则决定，可读性较差。

建议明确指定：

XML
filePattern="/logs/app-%d{yyyy-MM-dd}.log"

生产环境中明确日期格式能够避免不同版本、不同环境产生差异。

---

3. Filename 与 filePattern 混淆

很多错误来自于理解错误。

例如：

XML

    name="File"
    fileName="/logs/app-%d{yyyy-MM-dd}.log"
    filePattern="/logs/app-%d{yyyy-MM-dd}.log">

这是错误设计。

fileName 表示当前写入文件，不应该包含动态日期。

正确：

XML
fileName="/logs/app.log"

filePattern="/logs/app-%d{yyyy-MM-dd}.log"

运行过程：

当前：

app.log

滚动后：

app-2026-10-02.log

---

4. %i 使用错误导致文件覆盖

当同时配置时间和大小滚动时，通常需要 %i。

错误：

XML
filePattern="/logs/app-%d{yyyy-MM-dd}.log"

配置：

XML

 size="10 MB"/>

一天内如果超过多个文件大小限制，可能产生：

app-2026-10-02.log

重复滚动问题。

推荐：

XML
filePattern="/logs/app-%d{yyyy-MM-dd}-%i.log"

生成：

app-2026-10-02-1.log
app-2026-10-02-2.log
app-2026-10-02-3.log

---

5. 压缩文件扩展名配置错误

Log4j2 支持根据扩展名自动压缩：

正确：

XML
filePattern="/logs/app-%d{yyyy-MM-dd}.log.gz"

错误：

XML
filePattern="/logs/app-%d{yyyy-MM-dd}.gz.log"

错误顺序可能导致压缩功能无法正常识别。

常见支持格式：

.gz
.zip

例如：

XML
app-2026-10-02.log.gz

---

RollingFileAppender 启动时报 Filename Pattern 错误

项目启动时，如果出现类似错误：

ERROR Unable to locate appender "RollingFile"

或者：

Pattern contains an invalid conversion pattern

通常可以从以下几个方向排查。

---

检查 Log4j2 配置文件名称

Log4j2 默认加载：

log4j2.xml

也支持：

log4j2-spring.xml

如果 Spring Boot 项目中使用：

XML

必须使用：

log4j2-spring.xml

否则部分扩展配置无法解析。

---

检查 XML 转义问题

路径中包含特殊字符时需要注意。

例如：

错误：

XML
filePattern="/logs/app-%d{yyyy-MM-dd HH:mm:ss}.log"

正确：

XML
filePattern="/logs/app-%d{yyyy-MM-dd-HH-mm-ss}.log"

文件名中不要包含：

:
*
?
"
<
>
|

这些字符在 Windows 环境尤其容易导致失败。

---

检查路径权限

Filename Pattern 本身正确，但目录不存在或没有权限，也可能表现为滚动失败。

例如：

XML
filePattern="/data/log/app-%d{yyyy-MM-dd}.log"

需要确认：

Bash
ls -ld /data/log

如果目录不存在：

Bash
mkdir -p /data/log

并给予应用用户写权限。

---

Spring Boot 中 RollingFileAppender 常见配置问题

Spring Boot 项目通常配置如下：

XML
 name="FILE"
             fileName="${LOG_PATH}/app.log"
             filePattern="${LOG_PATH}/app-%d{yyyy-MM-dd}-%i.log">

    
        
         size="50MB"/>
    

常见问题包括：

环境变量不存在

例如：

XML
filePattern="${LOG_PATH}/app-%d{yyyy-MM-dd}.log"

但是：

LOG_PATH

没有定义。

结果可能生成：

${LOG_PATH}/app-2026-10-02.log

或者启动失败。

解决：

application.properties：

properties
LOG_PATH=/data/logs

或者提供默认值：

XML
${LOG_PATH:-logs}

---

日期占位符被 Spring 占用

部分开发人员会错误写：

XML
filePattern="/logs/app-${date}.log"

Spring 会尝试解析变量。

Log4j2 日期变量必须使用：

XML
%d{yyyy-MM-dd}

而不是：

XML
${date}

---

如何快速定位 Filename Pattern 问题

可以按照以下顺序排查：

第一步：检查配置语法

启动时增加：

Bash
-Dlog4j2.debug=true

查看 Log4j2 加载过程。

---

第二步：验证 Pattern 是否有效

重点检查：

%d
%i
${变量}
路径
扩展名

是否符合规则。

---

第三步：关闭压缩测试

如果配置：

XML
.log.gz

出现异常，可以临时修改：

XML
.log

确认是否为压缩问题。

---

第四步：简化配置

先使用：

XML

    name="File"
    fileName="app.log"
    filePattern="app-%d{yyyy-MM-dd}.log">

确认正常后，再逐步增加：

• 文件大小限制。

• 压缩。

• 环境变量。

• 多级目录。

---

推荐的生产环境 RollingFileAppender 配置

一个较稳定的生产配置如下：

XML
 name="ApplicationLog"
             fileName="/var/log/app/app.log"
             filePattern="/var/log/app/app-%d{yyyy-MM-dd}-%i.log.gz">

    
        
            %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
        
    

    
         interval="1"/>
         size="100 MB"/>
    

     max="30"/>

该配置具备：

• 按天切割日志。

• 单文件大小限制。

• 自动压缩历史日志。

• 自动清理旧日志。

---

总结

Log4j2 RollingFileAppender 的 Filename Pattern 错误，大多数来源于日期格式错误、fileName 与 filePattern 使用混淆、变量解析失败以及路径权限问题。

排查时应重点关注：

1. %d 日期格式是否正确。

2. %i 是否满足多文件滚动需求。

3. fileName 是否保持固定名称。

4. filePattern 路径是否存在且可写。

5. Spring Boot 环境变量是否正确加载。

合理配置 RollingFileAppender，不仅可以避免日志滚动失败，还能提升生产环境日志管理效率，为系统故障排查提供可靠的数据支持。