前言：掌握配置，駕馭框架行為
struts.properties（或 struts.xml 中的 <constant>）是控制 Struts 2 運行時行為的中樞。本文整理了官方文檔中的核心屬性，按功能分類並附上中文說明與典型取值，供開發查閱。
1. 動作映射與擴展名
| 屬性名 | 說明 | 預設值 / 範例 |
|---|
struts.action.extension | URL 擴展名，用於識別請求是否映射到 Struts Action | action、do、jspa（如 login.do） |
struts.enable.DynamicMethodInvocation | 是否允許 URL 動態調用方法（如 action!method.action） | true / false（生產建議關閉） |
2. 核心配置與加載
| 屬性名 | 說明 | 預設值 / 範例 |
|---|
struts.configuration | Configuration 實作類全限定名 | org.apache.struts2.config.Configuration |
struts.configuration.files | 啟動時自動加載的配置檔列表（逗號分隔） | struts-default.xml,struts-plugin.xml,struts.xml |
struts.configuration.xml.reload | 開發模式下是否熱重載 XML 配置 | true / false |
3. 開發模式與除錯
| 屬性名 | 說明 | 預設值 |
|---|
struts.devMode | 開發模式：啟用詳細錯誤頁、配置熱重載、OGNL 表達式除錯等 | false（生產必須關閉） |
4. 國際化（i18n）
| 屬性名 | 說明 | 預設值 / 範例 |
|---|
struts.custom.i18n.resources | 額外加載的國際化資源檔（不含 .properties 後綴） | globalMessages,myApp |
struts.i18n.encoding | 國際化訊息編碼 | UTF-8 |
struts.i18n.reload | 是否自動重載國際化資源檔 | false |
struts.locale | 預設 Locale | zh_CN、en_US |
5. 多部分請求（檔案上傳）
| 屬性名 | 說明 | 預設值 / 範例 |
|---|
struts.multipart.maxSize | 單次上傳最大尺寸（位元組） | 2097152 (2MB) |
struts.multipart.parser | MultiPartRequest 解析器實作 | org.apache.struts2.dispatcher.multipart.JakartaMultiPartRequest |
struts.multipart.saveDir | 上傳檔案臨時儲存目錄 | 系統臨時目錄 |
6. 物件工廠與 Spring 整合
| 屬性名 | 說明 | 預設值 |
|---|
struts.objectFactory | ObjectFactory 實作類（Spring 整合必設） | com.opensymphony.xwork2.spring.SpringObjectFactory |
struts.objectFactory.spring.autoWire | Spring 是否自動裝配 Action | true |
struts.objectFactory.spring.useClassCache | Spring 是否使用類快取 | true |
7. 靜態資源服務
| 屬性名 | 說明 | 預設值 |
|---|
struts.serve.static | Struts Filter 是否直接服務靜態資源（CSS/JS/圖片） | true |
struts.serve.static.browserCache | 靜態資源是否設定瀏覽器快取 Header | true |
8. UI 模板與主題
| 屬性名 | 說明 | 預設值 |
|---|
struts.ui.theme | 預設 UI 主題 | xhtml、simple、css_xhtml |
struts.ui.templateDir | UI 模板目錄 | template |
struts.tag.altSyntax | 是否啟用標籤替代語法 | false |
9. Freemarker / Velocity / XSLT 整合
| 屬性名 | 說明 | 備註 |
|---|
struts.freemarker.manager.classname | FreemarkerManager 實作類 | 自定義指令/共享變數時用 |
struts.velocity.configfile | Velocity 配置檔路徑 | |
struts.velocity.toolboxlocation | Velocity Toolbox 位置 | |
struts.xslt.nocache | XSLT 模板是否禁用快取 | false |
10. URL 生成與端口
| 屬性名 | 說明 | 預設值 |
|---|
struts.url.http.port | 生成 HTTP URL 使用的埠 | 80 |
struts.url.https.port | 生成 HTTPS URL 使用的埠 | 443 |
struts.url.includeParams | URL 生成時預設包含請求參數模式 | none/get/all |
11. 範例配置片段
struts.i18n.reload=true
struts.devMode = true
struts.configuration.xml.reload=true
struts.continuations.package=org.apache.struts2.showcase
struts.custom.i18n.resources=globalMessages
# struts.action.extension=jspa
struts.url.http.port = 8080
struts.freemarker.manager.classname=customFreemarkerManager
struts.serve.static=true
struts.serve.static.browserCache=false
struts.codebehind.defaultPackage=person
最佳實踐提醒
- 生產環境務必設定
struts.devMode=false，避免效能損耗與資訊洩露。
- 檔案上傳大小限制
struts.multipart.maxSize 需配合伺服器容器設定（如 Tomcat maxPostSize）。
- Spring 整合時，
struts.objectFactory 指向 SpringObjectFactory 並確保 Spring 容器已啟動。
- 靜態資源建議由 Nginx/Apache 直接服務，生產環境可關閉
struts.serve.static。
