常见问题 FAQ
插件支持哪些 IDE 版本？
IntelliJ IDEA 2024.3 及以上（since-build=243）。兼容 2024.3 / 2025.3 / 2026.2 全系列。Community 与 Ultimate 均支持，但「执行 SQL」功能需 Ultimate + Database 插件。
为什么 gutter 图标不显示？
Gutter 图标仅在以下位置出现：
- Wrapper 链末尾行（
.eq()等终止调用所在行） - mapper XML 的
<select>/<update>等语句行 - Java Mapper 接口中
@Select等注解行 - Hibernate HQL 调用行（
session.createQuery(...)）与 JPA@Query注解行、Repository 推导方法行
确认光标位于上述位置；如仍不显示，检查设置页「代码左侧显示预览 SQL 图标」是否开启。多行 + 拼接的 HQL 字符串同样支持 gutter 图标。
为什么 mapper XML 里没有 SQL 语法高亮或代码补全？
mapper XML 内语句的语法高亮（关键字 / 字符串 / 注释着色、#{} / ${} 占位底色、test 等属性表达式着色）与语句内补全，由本插件自己提供（语言注入 + 自研高亮器），不需要用户配置 SQL 方言。完全看不到时按以下顺序排查：
- 插件版本是否包含该能力：mapper XML 注入着色是较新的能力，2026.10.9 及更早的发行版不含；该能力自 2026.10.13 起提供，请升级到最新版（升级后重启 IDE）；
- 文件是否被识别为 mapper：根标签须为
<mapper>（带namespace）——mapper出现在根标签里才会启用注入； - 是否与其他 MyBatis 插件冲突：装了其他 MyBatis 插件（如 MyBatisCodeHelperPro）时，本插件只在对方已占用的区间上让位（例如参数占位符
#{}），语句其余部分照常着色，不会整段消失； - 补全依赖索引：补全候选来自「实体类 / Mapper 接口可被解析」，项目依赖需已导入、索引已就绪（依赖未导入或索引进行中时不产候选）；
- 语句内补全的手动触发键是
Ctrl+Space。
高亮由设置页「界面与操作」的**「mapper XML 语法高亮（关键字 + 参数占位着色）」**总控（默认开），若被误关会整片无色，可先确认它处于开启状态。
需要配置 SQL 方言才有高亮吗？
不需要。mapper XML 里的 SQL 高亮和补全由本插件提供，不依赖 SQL 方言配置。
编辑器里若出现 SQL dialect is not configured.，那是 IDE 平台的提示——Ultimate 的 SQL 注入对 mapper XML 语句文本给出的弱警告，不是本插件的报错。想消除它、或想用平台的 SQL 能力（语句解析、对象跳转、直接执行）时，到 Settings → Languages & Frameworks → SQL Dialects 把项目（或 mapper 文件所在目录）指到实际方言即可。配了是锦上添花，不配也不影响本插件的高亮。
配置数据源是为了让 XML 里有高亮吗？
不是。数据源是执行类能力的前置：执行 SQL、EXPLAIN 要先在 Database 工具窗口配好数据源（Ultimate 的 Database 插件）。编辑器的语法高亮和补全不读数据源，不配数据源一样有高亮；配好数据源后，列名补全会额外并入数据库真实列与注释（详见功能详解 · SQL 代码补全），JOIN 图节点也会带出数据库真实列注释。
支持 MyBatis-Plus-Join（MPJ）联表查询吗？
支持。MPJLambdaWrapper 与 MPJQueryWrapper 联表预览、以及 MPJ 形态的 SQL→Java 反向转换均已实现。反向转换选择 MPJ 形态时，项目需引入 mybatis-plus-join 依赖（1.5.6+）。
为什么 JPA 的 findAllById 没有预览？
JPA 派生查询的第一批尚未包含 findAllById 这类 IN 展开形态，暂无法生成预览，后续版本补齐，已列入开发路线。
预览 SQL 与实际运行 SQL 有差异吗？
预览目标是对齐 MP 运行时语义，以下差异是静态求值的固有特性，语义等价、仅文本不同：
| 差异 | 说明 |
|---|---|
| 静态常量内联 | in(col, DicConstants.A) 等静态 final 常量被求值内联（预览 IN (1)）；MP 运行时渲染 IN (?) |
| 集合单占位符 | in(col, 集合变量) 运行时大小无法静态展开 → 预览 IN (?)；面板输入框支持逗号分隔回填 |
| 分页字面量计算 | page(new Page<>(1, 10), wrapper) 直接计算 LIMIT 0, 10；运行时渲染 LIMIT ?, ? |
? 占位符能不能识别并替换为实际值？
可以。左侧面板输入框支持逗号分隔多值回填（输入 1,2,3 → 渲染为 (1, 2, 3)）。LIKE 参数自动拼百分号。按字段类型决定是否加引号。设置页「替换 ? 占位符」默认开启，关闭后变量也渲染为 ?。
EXPLAIN 点击失败或没反应？
最常见原因是未配置数据源：「EXPLAIN」与「执行 SQL」一样依赖 IntelliJ IDEA Ultimate 的 Database 工具窗，先在里面配好数据源再试。Oracle 的计划行落在会话级 PLAN_TABLE、语句本身返回 0 行，按面板指引在同一连接的数据库端查 DBMS_XPLAN.DISPLAY 即可看到；SQL Server 的计划 XML 出现在原生控制台的附加结果页签里。执行出错时错误信息直接显示在面板内，不会弹窗。
SQL 日志捕获不到 SQL 怎么办？
先看面板空态给出的诊断——它会显示增强捕获通道当前的状态（未开启 / 等待应用进程 / 已挂载 / 已回落）和控制台已扫描行数，并按档给出下一步。按通道看：
增强捕获（默认通道）
- 总开关被关掉了：到设置页「增强捕获」重新勾上——默认开启且勾选即授权，不需要额外确认
- 还没跑过项目：增强捕获随应用进程挂载，先运行 / 调试一次项目
控制台通道（增强捕获不可用时的回落）
- 应用日志要包含
Preparing:/Parameters:；==> Preparing:形态需在设置页开启「混合前缀」 - 参数行可能被日志级别挡掉，通常要开到 TRACE
- 检查是否被「移除包含关键字」过滤规则命中
- 确认日志输出到运行控制台，而不是独立日志文件
gutter 右键「最近执行记录」是空的？
「最近执行记录」从本次会话捕获的日志里反查该位置附近的执行，需要日志捕获处于开启状态，且此前已捕获过该位置的执行。
新会话刚启动、还没跑过 SQL 时，对话框会显示空态文案，属正常现象。日志一直捕获不到时，先按上一节的步骤排查。
实时日志「跳转到源码」跳不准怎么办？
跳转只认插件真实捕获到的位置，不做表名猜测回退。增强捕获通道的条目自带执行时的真实调用栈，落点精确；控制台捕获通道的日志本身不含调用位置，需要按下文配置拦截器才有精确落点。
要精确跳转，把插件自带的自包含拦截器 SqlSourceInterceptor 复制到项目并注册为 MyBatis-Plus InnerInterceptor，详见功能详解 · 跳转到源码。
拦截器文件在插件仓库 docs/instrumentation/SqlSourceInterceptor.kt；不配置也不影响其他功能。
自动弹出的日志窗口能彻底关掉吗？
可以。「发现 SQL 时自动打开日志窗口」默认开启，捕获到第一条 SQL 时会自动展开日志窗口；手动关掉后，本次会话内不会再自动弹出。想彻底关闭，在设置页把「发现 SQL 时自动打开日志窗口」关掉即可；重新开启该开关或重启 IDE 后恢复自动展开。
升级后 SQL 历史记录去哪了？
v2026.9.2 起，插件在项目内的数据目录由 .idea/mybatis-plus-sql-visualizer/ 改名为 .idea/sql-visualizer/（历史 SQL 与执行临时文件）。此次更名不做旧数据迁移，升级后历史 SQL 从新目录起算重新积累。
如需保留旧记录，可手动把旧目录 sql-history/ 下的 .sql 文件复制到新目录。
升级后我的 SQL 方言怎么变了？
v2026.9.18 起，数据库方言默认改为「智能推断（跟随数据源）」：插件只把 SQL 数据源当候选自动判定方言（Redis 一类非 SQL 数据源不算），配置证据按模块收窄并优先看激活 profile；兜底也不再硬编码 MySQL——拿不到数据源时按配置里的 JDBC URL 与 SQL 方言特征取共识，再退项目 / 全局设置。老配置里如果从未手动设置过方言，升级后会自动进入推断模式（原默认 MySQL）。
想固定某个方言，在设置页把方言手动选定即可，分页 / upsert 等渲染都按选定方言走；随时可以切回「智能推断」。
SQL → Java 反向转换生成的代码能直接编译吗？
可以。生成代码严格基于 MyBatis-Plus 公开 API（以本地 jar 反编译为唯一权威），不含虚构方法。自动推断实体类后使用 Lambda 形态生成类型安全代码；找不到实体时回退字符串列 QueryWrapper。
如何切换插件界面语言？
Settings → Tools → SQL Visualizer → 界面语言。支持 简体中文 / English / 跟随系统。插件语言独立于 IDE 语言设置，切换后重新打开预览弹窗即生效。
内网 / 无外网环境能用吗？
可以，核心功能完全离线——预览、参数回填、反向转换、日志还原、JOIN 图、格式化、CRUD 生成都不需要外网，插件不发任何使用数据，也没有账号校验。仅「检查更新」与「提交反馈」两个可选入口会访问外网，失败时只提示不阻塞。
内网部署另需注意两点：执行 SQL 所需的 JDBC 驱动要提前预置（驱动缺失时是 IDE 平台联网下载），以及可用系统属性把更新源换成内网地址。详见内网与离线环境。
支持哪些数据库方言的分页语法？
11 种：MySQL、PostgreSQL、Oracle、SQL Server、H2、SQLite、MariaDB、DM（达梦）、KingBase（金仓）、OceanBase、openGauss。分页子句和 upsert 冲突子句按方言差异渲染。
快捷键冲突怎么办？
在插件设置页点击快捷键旁的「编辑」按钮重新录制。若与其他插件冲突，弹窗提供「使用」（共存）或「强制使用」（抢占）选项。也可在 Settings → Keymap 中直接修改。
分页查询的 COUNT 语句是从哪来的？
那是「模拟分页拦截器」在预览里按 MyBatis-Plus PaginationInnerInterceptor 的运行时行为补出来的：mapper 方法 / XML / 注解语句带 Page / IPage 参数时，预览会在原语句后尾追分页子句（如 LIMIT ?, ?）并并列产出一条 COUNT 包裹（SELECT COUNT(*) FROM (...) TOTAL，带注释说明出处）。searchCount=false 与手写 LIMIT 的语句只产其一；COUNT 附在面板底部，滚到底才看得到。不想要就在设置页「SQL 预览」关掉总开关，或用子开关「附分页 COUNT 查询预览」只去掉 COUNT 那半。
预览里能体现数据权限（DataPermission）的影响吗？
数据权限是运行期由拦截器动态追加条件的，静态预览看不到。插件给了两个辅助手段：设置页「SQL 预览」的**「数据权限模拟条件」可以手填一段 WHERE 片段（如 dept_id IN (1,2,3)），追加到 SELECT / UPDATE / DELETE 末尾，预览「生效后」的形态；另可打开「显示 DataPermissionInterceptor 运行时差异提示」**，让预览警告区提醒这条语句在运行时会被动态改写。
JdbcTemplate 里手写的字符串 SQL 能预览吗？
可以。设置页「SQL 预览」的「启用 JdbcTemplate SQL 字符串预览」默认开启：queryForList / update 等方法的字符串 SQL 实参会有预览图标，也能用 Alt+Shift+Q 触发；NamedParameterJdbcTemplate 的 :name 命名参数可以回填。
执行计划为什么没在面板里渲染成表格？
默认就是走原生数据库控制台——「预览面板内结构化渲染 EXPLAIN」是实验特性、默认关闭（表格形态的交互经验收评估不如原生控制台）。想要面板内结构化渲染可在设置页开启：MySQL 家族出表格行、PostgreSQL 家族出 FORMAT JSON 树并附索引建议；其余方言（TEXT / XML 不硬解析）与任何失败路径都自动回退原生控制台，两条通道并存。
参数值每次都要重填吗？
不用。预览面板的参数区有「预设」：默认预设会把你填过的值记住并在下次预览同一声明方法时自动召回（预设按方法隔离——两个方法各自的参数互不干扰；即便你改过 SQL 文本，仍会按该方法最近一次保存回落），管理预设里可以保存多套具名参数组合（如「线上样例」「边界值」）随时切换；动态条件区还有「全不选 / 清除」用来快速清空当前条件。
预估影响行数为什么不可用？
这个动作只对单条 UPDATE / DELETE 有效，以下形态会直接给出原因而不试算：语句无法解析、多语句、非 UPDATE / DELETE、JOIN / 多表写（COUNT 会把被 JOIN 匹配多次的行重复计数）、无 WHERE（全表 COUNT 就是全表扫描）、WHERE 过于复杂（超长子查询谓词，成本不可控）。另外若当前没有绑定数据源，会先弹数据源选择器，选定后自动重试。
AI 上下文里为什么还有原始值？
「复制为 AI 上下文」只对命中规则的敏感字面量打码（密码类列名、身份证 / 手机号形态），普通字符串仍保留原文——例如 name = 'tom' 不会被当成敏感值。所以这个块不承诺整段无机密，复制到外部 AI 之前请自己看一遍再删改。想要更严的出口可以开启「展示与导出脱敏」，或在复制前手动清理。（这个块是版本化诊断投影，复制过程不请求数据库、不调用网络，计划摘要只取本会话已取得的结果。）
EXPLAIN 计划历史为什么默认不保存？
原始执行计划未脱敏，谓词里可能带业务值、凭据或密钥。所以「跨会话保留原始 EXPLAIN 计划」默认关闭，关闭时计划只在当前会话内可比。要跨会话对比需在设置页显式开启；开启后按项目 + 数据源 UUID + 方言 + SQL 指纹隔离保存，清除预览历史会一并删除。
反馈问题需要提供什么信息？
请到 官网需求池 提交反馈。建议附上：
- 插件版本号（设置页「内部构建号」可一键复制）
- IDE 版本（
Help → About） - 复现步骤与示例代码
- 相关日志或截图