Java 17 默认不读取系统级 tnsnames.ora，必须显式配置 TNS_ADMIN 环境变量或改用完整 TNS 字符串，否则必报 ORA-12154；因 Oracle JDBC Thin 驱动（ojdbc11+）完全不依赖 Oracle Home，仅支持 TNS_ADMIN 指向合法 tnsnames.ora 或直传标准格式 TNS 描述符。
Java 17 默认不读取系统级 tnsnames.ora，必须显式配置 TNS_ADMIN 环境变量或改用完整 TNS 字符串 —— 否则 100% 触发 ORA-12154。
为什么 Java 17 连不上 tnsnames.ora 里的别名？
Oracle JDBC Thin 驱动（ojdbc11.jar 及以上，含 Java 17 支持）**完全不依赖客户端 Oracle Home 或 tnsnames.ora 文件**。它只认两种方式：一是直接传入完整的 TNS 描述符字符串，二是通过 TNS_ADMIN 环境变量指向一个有效的 tnsnames.ora 目录（且该文件语法必须严格合规）。你本地 SQL*Plus 能连上，不代表 Java 应用能连上——这是最常见的认知偏差。
常见错误现象：SQLException: IO Error: The Network Adapter could not establish the connection 或更典型的 ORA-12154: TNS:could not resolve the connect identifier specified，往往就卡在这一步。
- Java 进程启动时不会自动扫描
$ORACLE_HOME/network/admin - IDE（如 IntelliJ）的运行配置里没继承系统环境变量，
TNS_ADMIN就是空的 - 即使设置了
TNS_ADMIN，路径末尾带斜杠、目录不存在、文件权限不足，都会静默失败
设置 TNS_ADMIN 环境变量的实操要点
不是“设了就行”，而是要确保 Java 进程在启动前已加载该变量，且指向的路径下有合法的 tnsnames.ora。
立即学习“Java免费学习笔记（深入）”；
- Linux/macOS：在启动 Java 前执行
export TNS_ADMIN=/etc/oracle/net（推荐绝对路径，避免相对路径歧义） - Windows：用
set TNS_ADMIN=C:\oracle\net（CMD）或$env:TNS_ADMIN="C:\oracle\net"（PowerShell），注意不要带中文路径或空格 - Spring Boot 应用：在
application.properties中加spring.datasource.hikari.data-source-properties.TNS_ADMIN=/etc/oracle/net（仅对 HikariCP 有效，且需驱动支持） - 验证是否生效：在 Java 代码中打印
System.getenv("TNS_ADMIN")，必须非 null 且路径可读
用完整 TNS 字符串替代 tnsnames.ora（推荐给新项目）
绕过文件依赖最稳妥的方式：把 tnsnames.ora 里某条目的内容直接拼进 JDBC URL。Java 17 + ojdbc11.jar 完全支持这种写法，且无需任何环境变量。
例如 tnsnames.ora 中有：
ORCLPDB = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = db.example.com)(PORT = 1521)) (CONNECT_DATA = (SERVICE_NAME = orclpdb.local)))
对应 JDBC URL 写成：
jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orclpdb.local)))
- 所有括号必须闭合，等号前后**不能有空格**，大小写敏感（
PROTOCOL、HOST、SERVICE_NAME必须全大写） - URL 中的括号、斜杠、冒号都要做 URL 编码吗？不用 —— JDBC Thin 驱动原生解析该格式，直接传原始字符串即可
- 如果服务名含特殊字符（如点号、下划线），保持原样；但整个字符串建议用单引号包裹，避免 shell 解析出错
tnsnames.ora 文件本身容易被忽略的硬性规则
即便你决定用 TNS_ADMIN，文件内容稍有偏差，Java 仍会报 ORA-12154，因为驱动底层调用的是 Oracle 的 TNS 解析器，容错率为零。
-
ORCLPDB = (DESCRIPTION = ...)—— 等号前后**绝对不能有空格**，否则解析失败 -
SERVICE_NAME是首选，SID在 12c+ 多租户环境下基本失效；确认数据库实际服务名用SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL; - 文件编码必须是 ASCII 或 UTF-8 无 BOM；Windows 记事本保存易带 BOM，建议用 VS Code 或 vim 编辑并检查编码
- 每行末尾不能有多余空格或制表符，注释用
#开头，且必须独占一行或位于行尾（但行尾注释在某些驱动版本中不可靠，建议不用）
真正卡住人的，从来不是“怎么写”，而是“哪里多了一个空格、少了一个括号、路径少了一级、环境变量没传进 JVM”。这些细节不验证，光改代码没用。
