Apache MyFaces 4.1.3 配置参数详解

目标：详解 Apache MyFaces Core 4.1.3 的全部配置参数。MyFaces 配置通过 web.xml 的 <context-param> 注入，分「规范级 jakarta.faces.*」与「MyFaces 专有 org.apache.myfaces.*」两类。本文参数名、默认值与取值均取自实测环境：LOG_WEB_CONTEXT_PARAMS=true 时 MyFaces 启动日志打印的真实默认值，以及 4.1.3 源码 MyfacesConfig.java 的 @JSFWebConfigParam 注解。已在 Ubuntu 22.04.5 + JDK 17 + Tomcat 10.1.60 + MyFaces 4.1.3 环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Java：OpenJDK 17.0.20.1；Maven 3.6.3
• Web 服务器：Apache Tomcat 10.1.60（/opt/tomcat，systemd 托管，堆 -Xms256m -Xmx512m -Xmn128m）
• MyFaces：myfaces-api 4.1.3 + myfaces-impl 4.1.3
• 配置文件位置：/root/myfaces-demo/src/main/webapp/WEB-INF/web.xml（打包后为 WEB-INF/web.xml）
• 源码参考：myfaces-impl-4.1.3-sources.jar 内 org/apache/myfaces/config/webparameters/MyfacesConfig.java

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache MyFaces 4.1.3 指南》安装 JDK 17、Maven、Tomcat 10.1.60；
• 已按《Apache MyFaces 4.1.3 构建并运行示例应用指南》部署一个含 MyFaces 的 Web 应用（下文以 myfaces-demo 为例）。

三、参数查看与修改方式

3.1 方式一：启动日志打印全部参数（实测）

在 web.xml 中设置 org.apache.myfaces.LOG_WEB_CONTEXT_PARAMS=true，Tomcat 启动时 MyFaces 会把每个参数当前值与默认值打印到 /opt/tomcat/logs/catalina.out：

<context-param>
  <param-name>org.apache.myfaces.LOG_WEB_CONTEXT_PARAMS</param-name>
  <param-value>true</param-value>
</context-param>

实测日志片段（节选）：

Init context parameter found 'jakarta.faces.PROJECT_STAGE' set to 'Production'
No context init parameter 'jakarta.faces.STATE_SAVING_METHOD' found, using default value 'server'.
No context init parameter 'jakarta.faces.PARTIAL_STATE_SAVING' found, using default value 'true (false with 1.2 webapps)'.
No context init parameter 'jakarta.faces.SERIALIZE_SERVER_STATE' found, using default value 'false'.
No context init parameter 'jakarta.faces.FACELETS_SUFFIX' found, using default value '.xhtml'.
No context init parameter 'jakarta.faces.FACELETS_BUFFER_SIZE' found, using default value '1024'.
No context init parameter 'jakarta.faces.FACELETS_REFRESH_PERIOD' found, using default value '0, -1 in Production'.
Init context parameter found 'org.apache.myfaces.COMPRESS_STATE_IN_SESSION' set to 'false'
Init context parameter found 'org.apache.myfaces.CACHE_EL_EXPRESSIONS' set to 'alwaysRecompile'
Init context parameter found 'org.apache.myfaces.LOG_WEB_CONTEXT_PARAMS' set to 'true'
No context init parameter 'org.apache.myfaces.VIEWID_CACHE_SIZE' found, using default value '500'.
No context init parameter 'org.apache.myfaces.RESOURCE_HANDLER_CACHE_SIZE' found, using default value '500'.
No context init parameter 'org.apache.myfaces.USE_ENCRYPTION' found, using default value 'true'.
No context init parameter 'org.apache.myfaces.ALGORITHM' found, using default value 'AES'.
No context init parameter 'org.apache.myfaces.MAC_ALGORITHM' found, using default value 'HmacSHA256'.
No context init parameter 'org.apache.myfaces.WEBSOCKET_MAX_IDLE_TIMEOUT' found, using default value '300000'.
No context init parameter 'org.apache.myfaces.VIEW_POOL_MAX_POOL_SIZE' found, using default value '5'.
No context init parameter 'org.apache.myfaces.ERROR_HANDLING' found, using default value 'false, on Development Project stage: true'.

💡 该参数默认值即 dev-only（仅开发阶段打印）；生产环境建议保持默认或显式设为 false，避免启动日志刷屏。

3.2 方式二：从 4.1.3 源码注解查看

下载 myfaces-impl-4.1.3-sources.jar，MyfacesConfig.java 中每个参数常量上方都有 @JSFWebConfigParam(defaultValue="...", since="...", group="...") 注解，是参数的权威来源：

cd /opt/myfaces/jars
wget https://repo.maven.apache.org/maven2/org/apache/myfaces/core/myfaces-impl/4.1.3/myfaces-impl-4.1.3-sources.jar
unzip -p myfaces-impl-4.1.3-sources.jar org/apache/myfaces/config/webparameters/MyfacesConfig.java | grep -A1 "JSFWebConfigParam" | head -10

3.3 修改方式

所有参数都在 web.xml 中以 <context-param> 声明，修改后重启 Tomcat 生效：

systemctl restart tomcat

⚠️ 注意：org.apache.myfaces.CONFIG_REFRESH_PERIOD（配置热刷新周期，默认 2 秒）只在非 Production 工程阶段生效；Production 阶段修改 web.xml 后必须重启 Tomcat 服务。JVM 堆参数不在 web.xml 中，改 setenv.sh/systemd 的 CATALINA_OPTS。

四、参数总览

4.1 规范级参数（jakarta.faces.*）

4.2 MyFaces 专有参数（org.apache.myfaces.*）

五、核心参数分类详解

5.1 工程阶段与初始化

jakarta.faces.PROJECT_STAGE

指定工程阶段，直接影响错误页、资源缓存与热刷新行为。实测未设置时 MyFaces 日志为 Couldn't discover the current project stage, using Production，即默认 Production。

<context-param>
  <param-name>jakarta.faces.PROJECT_STAGE</param-name>
  <param-value>Development</param-value>
</context-param>

取值：Development（开发，显示详细错误模板 META-INF/rsc/myfaces-dev-error.xml）、Production（生产）、SystemTest、UnitTest。

org.apache.myfaces.INITIALIZE_ALWAYS_STANDALONE（默认 false）

置 true 时即使未发现 Web 服务器也强行初始化 Faces 环境（供单元测试）。默认 false，随服务器启动初始化。

5.2 视图与 Facelets

jakarta.faces.FACELETS_SUFFIX（默认 .xhtml）

Facelets 视图文件后缀。FacesServlet 按映射接管，视图按此后缀查找：

<context-param>
  <param-name>jakarta.faces.FACELETS_SUFFIX</param-name>
  <param-value>.xhtml</param-value>
</context-param>

jakarta.faces.FACELETS_REFRESH_PERIOD（默认 0，Production 阶段为 -1）

Facelets 模板热重载周期（秒）。Production 下为 -1 表示不热重载（性能最优）；开发期设小值可免重启改模板。

org.apache.myfaces.VIEWID_CACHE_SIZE（默认 500）

视图 ID 解析缓存容量。高并发多页面场景可调大，配合 VIEWID_EXISTS_CACHE_ENABLED/VIEWID_PROTECTED_CACHE_ENABLED/VIEWID_DERIVE_CACHE_ENABLED（均默认 true）使用。

5.3 状态保存

jakarta.faces.STATE_SAVING_METHOD（默认 server）

• server：视图状态存服务端会话，页面只带状态 ID（实测渲染出的 jakarta.faces.ViewState 为短串，如 MDI4MTE5ZGNjYzMzYTczYjAwMDAwMDAx）；
• client：状态加密后随页面往返（体积大，适合无会话/负载均衡场景）。

org.apache.myfaces.NUMBER_OF_VIEWS_IN_SESSION（默认 20，性能参数）

每个会话最多保留的视图快照数，超出后按序淘汰。浏览器多标签频繁回退场景可适当调大（如 25，本示例即设 25）：

<context-param>
  <param-name>org.apache.myfaces.NUMBER_OF_VIEWS_IN_SESSION</param-name>
  <param-value>25</param-value>
</context-param>

org.apache.myfaces.COMPRESS_STATE_IN_SESSION（默认 true，性能参数）

会话内状态压缩存储，节省内存；实测设 false 时日志为 Init context parameter found 'org.apache.myfaces.COMPRESS_STATE_IN_SESSION' set to 'false'。

org.apache.myfaces.RENDER_VIEWSTATE_ID（默认 true）

是否渲染 jakarta.faces.ViewState 隐藏域的 id 属性。多表单同页出现重复 id 时可设 false。

org.apache.myfaces.USE_FLASH_SCOPE_PURGE_VIEWS_IN_SESSION（默认 false）

使用 Flash 作用域时是否连带清理会话中的视图快照。

5.4 EL 表达式与视图池（性能）

org.apache.myfaces.CACHE_EL_EXPRESSIONS（默认 noCache）

EL 表达式缓存模式：noCache / strict / alwaysRecompile。实测默认 noCache 时启动日志为：

org.apache.myfaces.CACHE_EL_EXPRESSIONS web config parameter is set to "noCache". To enable view pooling this param must be set to "alwaysRecompile". View Pooling disabled.

设 alwaysRecompile 即开启视图池（视图复用、显著降低构建开销），同时要求 jakarta.faces.FACELETS_REFRESH_PERIOD=-1（Production 默认）且 org.apache.myfaces.STRICT_JSF_2_FACELETS_COMPATIBILITY=false（默认）：

<context-param>
  <param-name>org.apache.myfaces.CACHE_EL_EXPRESSIONS</param-name>
  <param-value>alwaysRecompile</param-value>
</context-param>

org.apache.myfaces.VIEW_POOL_MAX_POOL_SIZE（默认 5）

视图池最大容量；配合 VIEW_POOL_ENTRY_MODE（默认 soft，软引用）、VIEW_POOL_MAX_DYNAMIC_PARTIAL_LIMIT（默认 2）、VIEW_POOL_DEFERRED_NAVIGATION（默认 false）控制池化行为。

5.5 资源处理与缓存（性能）

org.apache.myfaces.RESOURCE_HANDLER_CACHE_SIZE（默认 500）与 RESOURCE_HANDLER_CACHE_ENABLED（默认 true）

JSF 资源（js/css 库）解析缓存。静态资源多的大型应用可调大缓存容量。

org.apache.myfaces.RESOURCE_MAX_TIME_EXPIRES（默认 604800000 毫秒 = 7 天）

浏览器对 JSF 资源的缓存有效期；配合 RESOURCE_CACHE_LAST_MODIFIED（默认 true）使用。

org.apache.myfaces.RESOURCE_BUFFER_SIZE（默认 2048）

资源输出缓冲区大小（字节）。

jakarta.faces.RESOURCE_EXCLUDES（默认 .class .jsp .jspx .properties .xhtml .groovy）

ResourceHandler 明确不托管、直接由 Web 服务器静态伺服的后缀列表。

5.6 会话与 Flash

org.apache.myfaces.FLASH_SCOPE_DISABLED（默认 false）

是否禁用 Flash 作用域。重定向后取不到 Flash 作用域中的值时，先确认未被设为 true。

org.apache.myfaces.AUTOCOMPLETE_OFF_VIEW_STATE（默认 one-time-code）

jakarta.faces.ViewState 隐藏域的 autocomplete 属性值（实测渲染为 autocomplete="one-time-code"）。

org.apache.myfaces.CLIENT_VIEW_STATE_TIMEOUT（默认 0）

客户端状态保存模式下状态超时（0 表示不超时）。

5.7 安全加密与 CSRF

org.apache.myfaces.USE_ENCRYPTION（默认 true）

服务端状态保存是否加密。加密需要 org.apache.myfaces.SECRET（会话密钥）或 SECRET.CACHE；不设置时 MyFaces 自动生成随机密钥（每次重启失效，多节点部署建议显式配置固定密钥）。算法默认 AES（org.apache.myfaces.ALGORITHM），填充模式默认 ECB/PKCS5Padding（ALGORITHM.PARAMETERS）；MAC 算法默认 HmacSHA256（MAC_ALGORITHM，密钥 MAC_SECRET/MAC_SECRET.CACHE）。

org.apache.myfaces.RANDOM_KEY_IN_CSRF_SESSION_TOKEN_LENGTH（默认 16）

CSRF 会话令牌随机数长度（字节）；算法默认 SHA1PRNG（RANDOM_KEY_IN_CSRF_SESSION_TOKEN_SECURE_RANDOM_ALGORITM，注意源码拼写 ALGORITM）。

5.8 调试与日志

org.apache.myfaces.LOG_WEB_CONTEXT_PARAMS（默认 dev-only）

启动时打印全部 context-param 的当前值/默认值（见 3.1 节）。

org.apache.myfaces.ERROR_HANDLING（默认 false, on Development Project stage: true）

错误页渲染开关：Production 默认 false（直接抛异常），Development 默认 true（渲染 META-INF/rsc/myfaces-dev-error.xml 模板）。

org.apache.myfaces.EL_RESOLVER_TRACING（默认 false，4.0 新增）

开启 EL 解析链路追踪日志，排查 #{...} 无法解析时使用。

org.apache.myfaces.DISABLE_OPTIONAL_EL_RESOLVER（默认 false，4.1.2 新增）

关闭可选 EL 解析器（如 CDI 之外的扩展解析器）。

六、生产配置模板

以下模板适用于 4GB 内存 / 多核 CPU 的常规 OLTP Web 服务（单 Tomcat 节点，堆上限 512MB 已按规范限定）：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
         version="6.0">

  <!-- 工程阶段：生产 -->
  <context-param>
    <param-name>jakarta.faces.PROJECT_STAGE</param-name>
    <param-value>Production</param-value>
  </context-param>

  <!-- 状态保存：server 模式，会话视图上限 25 -->
  <context-param>
    <param-name>jakarta.faces.STATE_SAVING_METHOD</param-name>
    <param-value>server</param-value>
  </context-param>
  <context-param>
    <param-name>org.apache.myfaces.NUMBER_OF_VIEWS_IN_SESSION</param-name>
    <param-value>25</param-value>
  </context-param>
  <context-param>
    <param-name>org.apache.myfaces.COMPRESS_STATE_IN_SESSION</param-name>
    <param-value>true</param-value>
  </context-param>

  <!-- 性能：开启视图池 -->
  <context-param>
    <param-name>org.apache.myfaces.CACHE_EL_EXPRESSIONS</param-name>
    <param-value>alwaysRecompile</param-value>
  </context-param>

  <!-- 资源缓存：7 天 -->
  <context-param>
    <param-name>org.apache.myfaces.RESOURCE_MAX_TIME_EXPIRES</param-name>
    <param-value>604800000</param-value>
  </context-param>

  <!-- 安全：固定会话密钥（多节点必须显式配置） -->
  <context-param>
    <param-name>org.apache.myfaces.SECRET</param-name>
    <param-value>q1w2e3r4q1w2e3r4q1w2e3r4q1w2e3r4</param-value>
  </context-param>

  <!-- 关闭参数打印，减少启动日志 -->
  <context-param>
    <param-name>org.apache.myfaces.LOG_WEB_CONTEXT_PARAMS</param-name>
    <param-value>false</param-value>
  </context-param>

  <servlet>
    <servlet-name>FacesServlet</servlet-name>
    <servlet-class>jakarta.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>FacesServlet</servlet-name>
    <url-pattern>*.xhtml</url-pattern>
  </servlet-mapping>

  <welcome-file-list>
    <welcome-file>index.xhtml</welcome-file>
  </welcome-file-list>
</web-app>

⚠️ 注意：SECRET 是状态加密密钥，示例为演示口令 q1w2e3r4 重复 4 次凑足长度，生产环境务必换成随机长密钥（建议 32 字节以上），多节点部署必须一致，否则会话状态跨节点无法解密。内存紧张的小型实例可把 NUMBER_OF_VIEWS_IN_SESSION 降到 10、VIEW_POOL_MAX_POOL_SIZE 保持默认 5。

七、常见问题

Q1：改了 web.xml 参数但重启后不生效？

① 确认修改的是最终 WAR 里的 WEB-INF/web.xml（源码改动后需重新 mvn package 并重新部署）；② org.apache.myfaces.CONFIG_REFRESH_PERIOD 仅非 Production 生效，Production 阶段必须 systemctl restart tomcat；③ 参数名拼写要精确（MyFaces 对未知参数名不会报错，只会静默忽略）。

Q2：启动日志看不到参数打印？

org.apache.myfaces.LOG_WEB_CONTEXT_PARAMS 默认 dev-only（仅 Development 阶段打印）。置为 true 强制打印（见 3.1 节），验证后记得改回。

Q3：设置 CACHE_EL_EXPRESSIONS=alwaysRecompile 但日志仍提示 View Pooling disabled？

视图池还需两个条件：jakarta.faces.FACELETS_REFRESH_PERIOD 为 -1（Production 阶段默认即是）以及 org.apache.myfaces.STRICT_JSF_2_FACELETS_COMPATIBILITY=false（默认）。若工程阶段是 Development 且 FACELETS_REFRESH_PERIOD 为 0，则无法开启。

Q4：org.apache.myfaces.SECRET 不设置行不行？

可以——MyFaces 自动生成随机密钥；但重启后所有已保存的会话状态无法解密（用户需重新登录）。多节点/负载均衡部署必须显式配置固定 SECRET 与 MAC_SECRET。

Q5：页面里找不到 org.apache.myfaces.DETECT_JAVASCRIPT / PRETTY_HTML 参数？

这两个参数在 2.x 时代存在，4.x 已移除，设置会被静默忽略。4.x 对应能力请用 jakarta.faces.PARTIAL_STATE_SAVING、org.apache.myfaces.RENDER_VIEWSTATE_ID 等现行参数。

Q6：会话状态过大导致内存上涨？

检查 COMPRESS_STATE_IN_SESSION（默认 true 已压缩）、NUMBER_OF_VIEWS_IN_SESSION（默认 20）与 PARTIAL_STATE_SAVING（默认 true）；确认 SERIALIZE_SERVER_STATE=false。内存仍紧张可改用 jakarta.faces.STATE_SAVING_METHOD=client（状态随页面往返，不占服务端内存）。

八、参考链接

• Apache MyFaces 官方配置文档：https://myfaces.apache.org/core41/myfaces-users-guide.html
• MyFaces Core 4.1（Maven Central，含 sources jar）：https://central.sonatype.com/artifact/org.apache.myfaces.core/myfaces-impl
• Jakarta Faces 规范（context-param 定义）：https://jakarta.ee/specifications/faces/