ORA-12154是客户端TNS名解析失败，纯本地问题，与数据库状态、网络、密码无关；需用tnsping定位实际加载的tnsnames.ora路径，检查TNS_ADMIN设置、文件语法（顶格、无空格/BOM）、sqlnet.ora中NAMES.DIRECTORY_PATH是否启用TNSNAMES，或改用Easy Connect验证。
ORA-12154 不是数据库没开、不是密码错、也不是网络不通——PL/SQL Developer 根本没发出任何 TCP 请求，它卡在“连谁都不知道”这一步。
PL/SQL Developer 没读到 tnsnames.ora 文件
绿色版或便携版 PL/SQL Developer 默认不继承系统环境变量，TNS_ADMIN 和 ORACLE_HOME 都为空，导致它完全找不到 tnsnames.ora。哪怕你把文件放在 C:\oracle\network\admin\ 下，它也不会自动去读。
- 必须手动设置：菜单
Tools → Preferences → Oracle → Connection，填入绝对路径的Oracle Home（例如D:\instantclient_19_2），注意不是指向tnsnames.ora文件，而是指向含network\admin子目录的父目录 - 若用 Instant Client，确保该目录下存在
network\admin\tnsnames.ora，且路径中不含中文或空格 - 改完后必须重启 PL/SQL Developer —— 缓存不会自动刷新
tnsnames.ora 条目格式一碰就失效
这个文件看着像配置，实则是 Oracle 客户端用 C 风格弱解析器读的文本，对空格、括号、换行极其敏感。一个空格就能让整段别名被跳过。
- 服务名必须顶格写：
ORCL =✅，ORCL =或ORCL =（等号前有空格）❌ - 最外层必须是
(DESCRIPTION = ...)，不能多一层括号，也不能漏右括号 - 避免 Windows 记事本保存的 UTF-8 BOM 头（推荐用 VS Code 或 Notepad++ 以 UTF-8 无 BOM 格式保存）
- 值区分大小写：Linux 下
SERVICE_NAME = orclpdb1和连接时写的@ORCLPDB1可能不匹配
Java 系应用（如 Navicat）根本不认系统级 tnsnames.ora
Navicat、DBeaver、甚至某些 Java 写的工具，底层用的是 ojdbc 驱动，默认不加载 tnsnames.ora，除非你显式指定位置。
- 必须加 JVM 参数：
-Doracle.net.tns_admin=/path/to/tnsnames/dir（路径末尾不带文件名） - 或代码中提前调用：
System.setProperty("oracle.net.tns_admin", "/path/to/dir")，且必须在创建DataSource前执行 - 更稳妥的做法是绕过文件：直接用 Easy Connect 格式，例如
jdbc:oracle:thin:@//192.168.1.100:1521/orclpdb1（注意双斜杠） - 确认 ojdbc 版本：ojdbc6 不支持
//host:port/service_name，会静默失败；ojdbc8+ 才完整支持，驱动类名必须是oracle.jdbc.OracleDriver
tnsping 是唯一可信的验证入口
别靠“我改了文件，应该好了”来判断。运行 tnsping ORCL（把 ORCL 换成你实际用的服务名），看第一行输出：
- 如果显示
Used parameter files: /path/to/sqlnet.ora，说明它正在读那个路径下的tnsnames.ora—— 接着检查该文件里是否有对应条目 - 如果该行为空，说明
TNS_ADMIN未生效或路径错误，此时设置环境变量并重新打开终端再试 - 如果提示
TNS-03505: Failed to resolve name，说明文件被读到了，但条目语法错误或服务名拼写不一致 -
tnsping不验证用户名密码，也不走数据库认证流程，它只回答一个问题：“这个名字，我认不认识？”
真正容易被忽略的是：多个 Oracle 客户端共存时（比如本地装了 11g 客户端又用了 19c Instant Client），TNS_ADMIN 指向了旧版本目录，而新工具却依赖新版本的解析逻辑 —— 这种错位不会报错，只会默默失败。
