ruoyi-vue-pro 框架替换验证码图片和水印（避坑指南）

在基于 ruoyi-vue-pro 进行二次开发时，替换登录页面的 AJ-Captcha 行为验证码（滑动拼图/点选）是一项常见需求。虽然看似简单，但由于缓存、文件格式和目录结构的要求，很容易踩坑。

本文总结了详细的替换步骤、图片规范以及开发过程中容易忽略的“雷点”。

1. 准备工作：图片规范

在动手之前，必须确保你的图片符合以下标准，否则后端无法加载或前端显示异常。

• 文件格式：必须是 .png 格式。

  • 注意：不要直接修改后缀名（如把 .jpg 改为 .png），建议使用转换工具重新保存。AJ-Captcha 默认只识别 PNG。
    可以用下面这个网址进行批量操作：
    https://www.iloveimg.com/zh-cn/convert-to-jpg

• 图片分辨率：建议 310 x 155 (像素)。

  • 这是 AJ-Captcha 的标准底图比例（2:1）。如果尺寸偏差太大，前端展示时会被拉伸变形。

• 文件名：支持中文或英文，无特殊要求。
  用下面这个网址进行图片裁剪
  https://www.iloveimg.com/zh-cn/resize-image

2. 替换步骤（后端）

第一步：定位目录与替换文件

不需要修改任何 Java 代码，也不需要把图片移到外部磁盘，只需要保持原项目的目录结构。

1. 打开项目路径：yudao-module-system/src/main/resources/images/jigsaw/。
2. 保留 original 文件夹（关键点）。
3. 将你准备好的 .png 图片放入 original 文件夹中。
4. 删除该文件夹下原有的默认图片（可选，保留也不影响）。

目录结构示意图：

yudao-module-system
 └── src
     └── main
         └── resources
             └── images
                 └── jigsaw
                     └── original  <-- 图片必须放在这里
                         ├── bg1.png
                         ├── bg2.png
                         └── bg3.png

第二步：修改水印（可选）

如果你想修改验证码右下角的文字（默认为“我的水印”或“AJ-Captcha”），可以在配置文件中设置。

打开 yudao-module-system/src/main/resources/application-dev.yaml (或 application.yaml)：

第三步：开启验证码（本地开发）

确保本地开发环境开启了验证码校验。

修改 application-local.yaml：

注意，前端也要同步进行修改

3. 清理与构建（至关重要）

很多时候替换了图片不生效，或者报错“底图未初始化”，是因为 Maven 缓存 导致的。Java 运行时读取的是 target 目录，而不是 src 目录。

操作步骤：

1. 在 IDEA 右侧 Maven 面板中，找到 yudao-module-system (或根项目)。
2. 双击 clean (清理 target 目录)。
3. 双击 compile (重新编译，将 src 下的新图片复制到 target)。
4. 重启 后端服务。

4. 常见“踩雷”点汇总

在操作过程中，如果遇到报错，请对照以下几点自查：

💥 雷点一：图片格式错误

• 现象：报错 底图未初始化成功。
• 原因：放入了 .jpg 或 .jpeg 图片。
• 解决：AJ-Captcha 默认只扫描 .png。请务必转换图片格式。

💥 雷点二：目录层级错误

• 现象：报错 底图未初始化成功，且图片格式已为 PNG。
• 原因：直接把图片放在了 images/jigsaw/ 根目录下，或者删除了 original 文件夹。
• 解决：系统默认会扫描 images/jigsaw/original 目录。请务必保留 original 文件夹并将图片放进去。

💥 雷点三：单词拼写错误

• 现象：启动报错 Invalid boolean value [ture] 或前端一直不弹窗。
• 原因：配置文件中 enable: true 误写成了 enable: ture。
• 解决：修正拼写。

💥 雷点四：Maven 缓存欺骗

• 现象：文件替换了，重启了，但浏览器看到的还是旧图，或者找不到图。
• 原因：IDEA 没有自动更新 target 目录下的资源文件。
• 解决：必须执行 Maven Clean -> Maven Compile 这一套组合拳。

💥 雷点五：前端配置不一致

• 现象：后端开启了验证码，点击登录按钮报错，前端不弹窗。
• 原因：前端 .env 文件配置未开启。
• 解决：检查前端项目根目录 .env.dev 或 .env.local，确保 VITE_APP_CAPTCHA_ENABLE=true，修改后需重启前端 (npm run dev)。

---

总结：替换验证码图片的核心在于“格式对（PNG）”、“位置对（original文件夹）”以及“清理缓存（Maven Clean）”。只要守住这三点，就能轻松搞定。