Struts 配置檔案遺漏 DTD 宣告導致 Resin 啟動失敗排查實錄

問題現象

專案遷移至 Resin 容器，啟動時拋出 SAXParseException，錯誤訊息指向 struts-config.xml 根元素。原本在 Tomcat 下正常運行，加入額外 XML 解析器配置後才暴露問題。

根本原因

• struts-config.xml **缺少 DOCTYPE 宣告**，導致解析器無法驗證元素結構，預設命名空間處理不一致。
• Tomcat 預設解析器寬容模式自動補齊；Resin 或啟用嚴格驗證的解析器則直接報錯。

修正前 (錯誤)

<?xml version="1.0" encoding="UTF-8"?>
<struts-config>
  <!-- 缺少 DOCTYPE -->
  <form-beans>...</form-beans>
</struts-config>

修正後 (Struts 1.0 DTD)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE struts-config PUBLIC
  "-//Apache Software Foundation//DTD Struts Configuration 1.0//EN"
  "https://struts.apache.org/dtds/struts-config_1_0.dtd">
<struts-config>
  ...
</struts-config>

後續問題：國際化 (i18n) 配置報錯

加入 <message-resources parameter="com.xxx.ApplicationResources"/> 後再次啟動失敗。

原因

• message-resources 元素 **Struts 1.1 才引入**，1.0 DTD 不支援。
• DTD 版本與 Struts 實際版本不匹配。

最終修正 (Struts 1.1 DTD)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE struts-config PUBLIC
  "-//Apache Software Foundation//DTD Struts Configuration 1.1//EN"
  "https://struts.apache.org/dtds/struts-config_1_1.dtd">
<struts-config>
  <message-resources parameter="com.xxx.ApplicationResources"/>
  ...
</struts-config>

最佳實踐總結

1. 永遠宣告正確的 DOCTYPE：根據專案實際使用的 Struts 版本選擇對應 DTD (1.0, 1.1, 1.2, 1.3)。
2. 本地化 DTD：將 DTD 檔案放入專案 WEB-INF/dtds/，並在 web.xml 或 EntityResolver 中映射，避免啟動時下載外部 DTD 導致網路延遲或離線構建失敗。
3. 遷移容器時全量驗證 XML：使用 xmllint --valid 或 IDE 驗證所有部署描述檔 (web.xml, struts-config.xml, hibernate.cfg.xml 等)。
4. 版本升級同步更新 DTD：Struts 升級時，務必同步更新 struts-config.xml DOCTYPE，否則新功能元素將無法通過驗證。

常見 Struts DTD 參考