JavaMail 常見安裝配置問題 FAQ (官方文檔中文整理)

前言

JavaMail API (javax.mail / jakarta.mail) 是郵件收發標準擴展，但不包含郵件服務器。本文整理官方 FAQ 核心條目：安裝部署、郵件服務器獲取、代理/防火牆穿透、CLASSPATH 設置、Linux unzip Bug、SecurityManager 權限、Web 容器整合、Servlet 演示配置、常見 ClassNotFound/ProviderNotFound 錯誤排查。

一、 安裝與 CLASSPATH

1. 解壓 javamail-.zip
2. 將 mail.jar 加入 CLASSPATH (或 Maven: com.sun.mail:jakarta.mail:2.0+)
3. **必須**同時安裝 JavaBeans Activation Framework (JAF)：activation.jar (JDK 6+ 已內置 javax.activation，JDK 9+ 需額外引入 com.sun.activation:jakarta.activation)

二、 郵件服務器誤區澄清

• JavaMail **不包含** SMTP/IMAP/POP3 服務器
• 需自備或租用郵件服務器 (企業 Exchange、Google Workspace、郵件服務商、自建 Postfix/Dovecot/Courier)
• 開發測試可用 GreenMail、MockMail、Dumbster 嵌入式假服務器

三、 代理與防火牆穿透

注意： socksProxyHost/Port 是**系統屬性**，影響整個 JVM 所有 TCP 連接，謹慎使用。

四、 Windows 設置 CLASSPATH (圖形界面)

1. 我的電腦 → 屬性 → 高級 → 環境變量
2. 系統變量 → 新建/編輯 CLASSPATH
3. 值：.;C:\Java\javamail-1.6\mail.jar;C:\Java\jaf-1.1.1\activation.jar (含當前目錄 .)

五、 Linux unzip Bug 導致 mail.jar 損壞

現象： 運行報 VerifyError: Illegal use of nonvirtual function call (類 com.sun.mail.pop3.POP3Store)
原因： 部分 Linux 發行版自帶 unzip 版本有缺陷，解壓破壞 JAR 內部條目 CRC
解決： 使用 JDK 自帶 jar xf javamail.zip 或升級 unzip 至 6.0+

六、 SecurityManager 權限配置 (JDK 1.2+)

應用若運行於 SecurityManager 下，需在政策文件 (java.policy) 授予：

grant codeBase "file:/path/to/mail.jar" {
  permission java.io.FilePermission "/path/to/mail.jar", "read";
  permission java.io.FilePermission "/path/to/activation.jar", "read";
  permission java.net.SocketPermission "smtp_host:25", "connect,resolve";
  permission java.net.SocketPermission "imap_host:143", "connect,resolve";
  permission java.net.SocketPermission "pop3_host:110", "connect,resolve";
  permission java.util.PropertyPermission "*", "read,write";  // 若使用 System.getProperties()
};

調試開關：-Dmail.debug=true、-Djavax.activation.debug=true、-Djava.security.debug=access:failure

七、 Web 容器整合 (Tomcat / Jetty / JBoss / WebLogic)

• 將 mail.jar、activation.jar 放入容器共享庫 (Tomcat: $CATALINA_HOME/lib/) 或應用 WEB-INF/lib/
• 修改 CLASSPATH 後必須完全重啟容器 (熱部署不生效)
• Servlet 中查找 Session：Session session = Session.getInstance(getServletContext().getInitParameter("mail.props"))

八、 常見 ProviderNotFound 錯誤排查

九、 Java Web Server (JWS) 歷史遺留

舊版文檔提及 jws.jar，**現代版本 (Java Web Server 2.0+) 無需且不再發布 jws.jar**，僅需 mail.jar + activation.jar。

結語

JavaMail 配置核心三點：1) mail.jar + activation.jar 雙雙在類路徑 2) 可達的 SMTP/IMAP/POP3 服務器 3) SecurityManager 場景授予讀取配置文件與網絡連接權限。現代專案建議使用 Spring Boot Mail Starter (org.springframework.boot:spring-boot-starter-mail) 自動裝配，消除手動配置錯誤。

1. 上一篇文章： Resin 1.1.4 + Apache 1.3 整合安裝配置教程 (Windows 環境)
2. 下一篇文章： FreeBSD Ports 安裝 Eclipse 3.1 + JDK 1.4.2 + JBoss 3.2.5 開發環境實錄

Java 相關知識

Java 併發容器：BlockingQueue 阻塞隊列家族全解析與生產者消費者實戰

BlockingQueue 核心價值 解決多線程環境下**高

Eclipse與WebSphere Studio項目交換功能：非倉庫環境下的代碼共享終極方案

代碼共享方式演進 團隊開發中代碼共享經歷五個階段： 版本倉

SSH 架構設計：分層架構與包結構規劃

作者從前端轉型 Java 後端，記錄自學 SSH 過程中對分

Ivy 教程 (7)：在多專案環境中使用 Ivy

場景：相互依賴的多模組應用 本教程模擬一個由六個模組組成的應