Java 整合 Kaptcha 驗證碼完整配置指南

Kaptcha 2.3 整合 Spring MVC / Servlet 專案

Kaptcha 是 Google 開源的驗證碼生成庫，支援圖片干擾線、字體、顏色、長度等豐富配置。本文說明從 Jar 引入到前後端完整整合流程。

1. 依賴引入

將 kaptcha-2.3.jar 放入專案 WEB-INF/lib 或 Maven 依賴：

<dependency>
    <groupId>com.google.code.kaptcha</groupId>
    <artifactId>kaptcha</artifactId>
    <version>2.3.2</version>
</dependency>

2. web.xml Servlet 配置

<!-- 驗證碼 Kaptcha -->
<servlet>
    <servlet-name>Kaptcha</servlet-name>
    <servlet-class>com.google.code.kaptcha.servlet.KaptchaServlet</servlet-class>
    
    <!-- 生產器實作 -->
    <init-param>
        <param-name>kaptcha.producer.impl</param-name>
        <param-value>com.google.code.kaptcha.impl.DefaultKaptcha</param-value>
    </init-param>
    
    <!-- 字體顏色 -->
    <init-param>
        <param-name>kaptcha.textproducer.font.color</param-name>
        <param-value>black</param-value>
    </init-param>
    
    <!-- 字元間距 -->
    <init-param>
        <param-name>kaptcha.textproducer.char.space</param-name>
        <param-value>10</param-value>
    </init-param>
    
    <!-- 邊框 -->
    <init-param>
        <param-name>kaptcha.border</param-name>
        <param-value>no</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.border.thickness</param-name>
        <param-value>0</param-value>
    </init-param>
    
    <!-- 字體大小 -->
    <init-param>
        <param-name>kaptcha.textproducer.font.size</param-name>
        <param-value>35</param-value>
    </init-param>
    
    <!-- 驗證碼長度 -->
    <init-param>
        <param-name>kaptcha.textproducer.char.length</param-name>
        <param-value>4</param-value>
    </init-param>
    
    <!-- 圖片尺寸 -->
    <init-param>
        <param-name>kaptcha.image.width</param-name>
        <param-value>150</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.image.height</param-name>
        <param-value>50</param-value>
    </init-param>
    
    <!-- 背景顏色漸層 -->
    <init-param>
        <param-name>kaptcha.background.clear.from</param-name>
        <param-value>255,255,255</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.background.clear.to</param-name>
        <param-value>255,255,255</param-value>
    </init-param>
    
    <!-- 字元集合（僅數字） -->
    <init-param>
        <param-name>kaptcha.textproducer.char.string</param-name>
        <param-value>0123456789</param-value>
    </init-param>
    
    <!-- 字體 -->
    <init-param>
        <param-name>kaptcha.textproducer.font.names</param-name>
        <param-value>Arial Black</param-value>
    </init-param>
    
    <!-- 干擾器：無干擾 -->
    <init-param>
        <param-name>kaptcha.noise.impl</param-name>
        <param-value>com.google.code.kaptcha.impl.NoNoise</param-value>
    </init-param>
</servlet>

<servlet-mapping>
    <servlet-name>Kaptcha</servlet-name>
    <url-pattern>/kaptcha.jpg</url-pattern>
</servlet-mapping>

3. 前端頁面整合

<img id="captchaImg" src="kaptcha.jpg" width="90" height="25" 
     onclick="refreshCaptcha()" alt="點擊更換驗證碼" style="cursor:pointer;" />
<input type="text" name="captcha" placeholder="輸入驗證碼" />

<script>
function refreshCaptcha() {
    // 加隨機參數防止瀏覽器快取
    document.getElementById('captchaImg').src = "kaptcha.jpg?" + Math.random();
}
</script>

4. 後端驗證

// Controller / Action 中
String sessionCaptcha = (String) request.getSession()
    .getAttribute(com.google.code.kaptcha.Constants.KAPTCHA_SESSION_KEY);

String userInput = request.getParameter("captcha");
if (sessionCaptcha != null && sessionCaptcha.equalsIgnoreCase(userInput)) {
    // 驗證通過
} else {
    // 驗證失敗
}

常用配置參數速查表

進階：自訂生產器

實作 com.google.code.kaptcha.Producer 介面，可完全控制圖片生成邏輯（如加入中文字、特殊干擾），再於 kaptcha.producer.impl 指定實作類。