Maven 整合 Tomcat 插件實現熱部署與中文亂碼徹底解決

Maven 整合 Tomcat 插件實現熱部署與中文亂碼徹底解決

Maven 是 Java 項目管理的標配，通過 tomcat7-maven-plugin（或 tomcat8/9-maven-plugin）可在無外部 Tomcat 安裝的情況下，實現「一鍵啟動、自動重載、編碼零配置」的開發體驗。本文從插件選型、核心配置、常用 Goal、亂碼根治、多環境隔離五個維度，輸出生產級最佳實踐。

一、 插件選型與坐標

建議：新項目優先 tomcat9-maven-plugin，Spring Boot 項目直接用 spring-boot-maven-plugin 內嵌容器。

二、 核心配置（pom.xml 完整版）

<plugin>
    <groupId>org.apache.tomcat.maven</groupId>
    <artifactId>tomcat9-maven-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
        <!-- 核心：解決 GET/POST 中文亂碼 -->
        <uriEncoding>UTF-8</uriEncoding>

        <!-- 應用上下文路徑：https://localhost:8080/myapp -->
        <path>/myapp</path>

        <!-- 端口 -->
        <port>8080</port>

        <!-- JVM 參數：開發機建議調大 -->
        <jvmArgs>-Xms512m -Xmx1024m -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=256m</jvmArgs>

        <!-- 熱部署掃描間隔（秒），0 關閉 -->
        <scanIntervalSeconds>3</scanIntervalSeconds>

        <!-- 掃描目標：編譯輸出目錄 + web 資源 -->
        <scanTargetPatterns>
            <scanTargetPattern>
                <directory>${project.build.directory}/classes</directory>
                <includes>**/*.class</includes>
            </scanTargetPattern>
            <scanTargetPattern>
                <directory>${project.basedir}/src/main/webapp</directory>
                <includes>**/*.jsp,**/*.html,**/*.js,**/*.css</includes>
            </scanTargetPattern>
        </scanTargetPatterns>

        <!-- 遠程部署認證（需 Tomcat manager 配置用戶） -->
        <server>tomcat9</server>
        <url>https://localhost:8080/manager/text</url>
        <username>admin</username>
        <password>admin</password>
    </configuration>
    <dependencies>
        <!-- 引入項目依賴的 JDBC 驅動等，避免 ClassNotFound -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.33</version>
        </dependency>
    </dependencies>
</plugin>

三、 亂碼根治：三層防線

1. URI 編碼（插件層）：<uriEncoding>UTF-8</uriEncoding> 解決 GET 請求參數亂碼（Tomcat 8+ 默認已為 UTF-8，但顯式配置更穩妥）。
2. 請求體編碼（Filter 層）：在 web.xml 或 Spring CharacterEncodingFilter 設置 forceEncoding=true，解決 POST 表單亂碼。
3. 數據庫連接編碼（JDBC 層）：URL 參數 characterEncoding=utf8&useUnicode=true&serverTimezone=Asia/Shanghai。

四、 常用 Goal 速查表

五、 IDEA 一鍵運行配置

1. 右側 Maven 面板 → 展開項目 → Plugins → tomcat9 → 右鍵 run → Create 'tomcat9:run'
2. 或 Run/Debug Configurations → + → Maven → Command line: tomcat9:run
3. 啟動後控制台輸出 Started Tomcat Server 即可訪問 https://localhost:8080/myapp

六、 多環境隔離（Profiles）

<profiles>
    <profile>
        <id>dev</id>
        <activation><activeByDefault>true</activeByDefault></activation>
        <properties>
            <tomcat.port>8080</tomcat.port>
            <tomcat.path>/myapp</tomcat.path>
        </properties>
    </profile>
    <profile>
        <id>test</id>
        <properties>
            <tomcat.port>8081</tomcat.port>
            <tomcat.path>/myapp-test</tomcat.path>
        </properties>
    </profile>
</profiles>

<!-- 插件配置引用屬性 -->
<configuration>
    <port>${tomcat.port}</port>
    <path>${tomcat.path}</path>
</configuration>

啟動：mvn tomcat9:run -Ptest

七、 避坑清單

• 類衝突：插件 <dependencies> 必須補全項目運行時依賴（JDBC、Redis 客戶端等），否則 ClassNotFoundException。
• 靜態資源不更新：確認 scanTargetPatterns 包含 src/main/webapp，且 IDEA 設置 Build → Build Project Automatically + Compiler → Build process → Register native library。
• 端口佔用：netstat -ano | findstr 8080 找 PID → taskkill /PID xxx /F。
• 遠程部署 403：Tomcat conf/tomcat-users.xml 配置 <role rolename="manager-script"/> <user username="admin" password="admin" roles="manager-script"/>。

Maven Tomcat 插件讓「寫代碼 → 保存 → 瀏覽器刷新驗證」成為流暢閉環，配合 scanIntervalSeconds 熱掃描與 UTF-8 全鏈路編碼，是 Java Web 開發效率的基石配置。