Java连接Oracle时“TNS加载失败”本质是ojdbc默认不读tnsnames.ora，仅当显式设置-Doracle.net.tns_admin后才尝试加载，且易因路径错误、文件格式不兼容（如21c新语法）、JDK17模块限制或静默fallback导致ORA-12154。
Java 连接 Oracle 时所谓“TNS 加载失败”，本质上是 ojdbc 驱动压根没去读 tnsnames.ora，或者读了但路径/内容/格式全错——这不是驱动“加载失败”，而是你误用了 TNS 机制。
别让 JVM 去找 tnsnames.ora
绝大多数 Java 应用根本不需要、也不该依赖本地 tnsnames.ora。JDBC Thin 驱动默认不读它，除非你显式设置系统属性 oracle.net.tns_admin。一旦设了，又配错路径或文件内容，就会触发类似 ORA-12154 的假象。
- 检查代码或启动参数是否设置了
-Doracle.net.tns_admin=/path/to/tns；如果没这个需求，直接删掉 - 确认 classpath 里没有残留的
sqlnet.ora或错误的tnsnames.ora（尤其打包进 jar 时容易混入） - 用
System.getProperty("oracle.net.tns_admin")打印实际值，避免被父进程或容器环境意外注入
改用直连 URL，绕过所有 TNS 解析
用完整地址格式，把 host/port/service_name 全写死，彻底甩开 tnsnames.ora 和解析逻辑。
- 优先用
jdbc:oracle:thin:@//host:port/service_name（双斜杠开头），这是 Oracle 12c+ 官方推荐格式，支持 PDB、RAC、SSL - 老版本 Oracle（如 11g）且必须用 SID 时，才用
jdbc:oracle:thin:@host:port:sid（注意是冒号结尾） -
host别写localhost：Docker、WSL、hosts 绑定异常时极不稳定，换成127.0.0.1或真实 IP - 验证 service_name 是否正确：连上数据库后执行
SELECT value FROM v$parameter WHERE name = 'service_names';
ojdbc 版本与驱动类名必须严格匹配
版本错位会导致 URL 解析行为异常——比如 ojdbc6 碰到 @//host:port/name 会静默忽略双斜杠，转而尝试查本地 TNS 文件，结果报 ORA-12154。
立即学习“Java免费学习笔记（深入）”；
- Oracle 12c+ 生产环境统一用
ojdbc8.jar（对应 JDK 8+），Maven 坐标是com.oracle.database.jdbc:ojdbc8 - 驱动类名必须是
oracle.jdbc.OracleDriver（不含driver.），旧的oracle.jdbc.driver.OracleDriver已废弃，某些版本会跳过新 URL 解析逻辑 - 检查 classpath 是否混入多个 ojdbc：
ClassLoader.getSystemResources("oracle/jdbc/OracleDriver.class")可列出所有加载路径，冲突时 JVM 可能随机选一个
监听器和服务名必须对得上
ORA-12154 看似是客户端问题，但根源常在服务端配置。URL 写对了，服务端没注册，照样解析失败。
- 确保监听器已启动：
lsnrctl status要看到目标service_name在SERVICE_NAME列中，而不是只显示UNKNOWN - 检查
listener.ora中SID_LIST是否包含你的实例，且GLOBAL_DBNAME与 URL 中的 service_name 一致（大小写敏感） - 如果是 CDB/PDB 架构，应用必须连 PDB 的 service_name（如
orclpdb1），不能连 CDB 根的 SID（如ORCL），否则监听器无法路由
真正难排查的点往往藏在“看似无关”的地方：比如 Docker 容器里 TNS_ADMIN 环境变量被继承、Spring Boot 的 YAML 把 @ 符号当占位符提前解析、甚至 IDE 的 Run Configuration 里悄悄加了系统属性。动手前先确认 JVM 实际加载了什么，比反复改配置更省时间。
