tnsnames.ora必须放在tns_admin指定路径或$oracle_home/network/admin下，语法需严格遵循oracle dsl规范，等号无空格、括号匹配、大小写敏感，非原生客户端须显式配置tns_admin或使用tns字符串。
tnsnames.ora 文件放错位置，90% 的 ORA-12154 错误就解决了。它不读当前目录、不扫描项目根目录，只认 TNS_ADMIN 环境变量或 $ORACLE_HOME/network/admin（Linux/macOS）/%ORACLE_HOME%\network\admin（Windows）下的文件。
tnsnames.ora 该放哪？路径不对连错地方都找不到
Oracle 客户端启动时，只在固定路径查找该文件。常见错误是把文件丢进项目目录、IDE 配置目录，甚至桌面——这些全无效。
- 默认路径：
$ORACLE_HOME/network/admin/tnsnames.ora（Linux/macOS）或%ORACLE_HOME%\network\admin\tnsnames.ora（Windows）；确认$ORACLE_HOME值：运行echo $ORACLE_HOME或echo %ORACLE_HOME% - 若设置了
TNS_ADMIN环境变量，则只读它指向的路径（如/etc/oracle/net），$ORACLE_HOME下的文件会被忽略 - Java、Python（cx_Oracle / oracledb）、Node.js 等非 Oracle 原生客户端，默认不读系统级
tnsnames.ora，必须显式设置TNS_ADMIN环境变量，或用完整 TNS 字符串连接 - 多个 Oracle 安装共存时，
$ORACLE_HOME指向哪个家，就找哪家的admin目录——不会自动合并多个文件
tnsnames.ora 条目怎么写？一个空格、少个括号都会报错
这不是普通 INI 文件，而是 Oracle 自研 DSL，解析器容错极低。语法错误直接导致 ORA-12154 或 TNS-03505。
- 基本结构必须是：
别名 = (DESCRIPTION = ...)，等号前后**绝对不能有空格**，=后第一个字符必须是( -
HOST和PORT必须大写，写成host或port:会失败；SERVICE_NAME推荐用（12c+ 多租户默认启用），SID多数已失效 - 括号必须严格匹配：每个
(都要有对应)，嵌套层级不深但不容错；建议用编辑器配对高亮检查 - 示例正确写法：
ORCLPDB = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = db-server)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = orclpdb)))
注意：没有换行也可（只要括号闭合），但换行+缩进更易排查；别名（如 ORCLPDB）区分大小写，客户端连接时必须完全一致。
为什么 SQL*Plus 能连上，但 Python cx_Oracle 却报 ORA-12545？
不是网络不通，是 cx_Oracle 默认不走 tnsnames.ora 查找逻辑——它需要你明确告诉它配置在哪，或者绕过文件直接传 TNS 字符串。
- 方案一：设置环境变量（推荐）：
export TNS_ADMIN=/path/to/your/tnsnames/dir（Linux/macOS）或set TNS_ADMIN=C:\oracle\net（Windows），再启动 Python 进程 - 方案二：代码中指定（cx_Oracle）：
cx_Oracle.init_oracle_client(config_dir="/path/to/tnsnames/dir")；oracledb v1.0+ 支持oracledb.defaults.config_dir = "/path/to/tnsnames/dir" - 方案三：不用文件，直接拼 TNS 字符串：
"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db-server)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orclpdb)))"——适合容器化或 CI 场景，但失去集中管理能力 - Java JDBC 不读
tnsnames.ora，需加 JVM 参数：-Doracle.net.tns_admin=/path/to/tnsnames/dir，或改用 Easy Connect：jdbc:oracle:thin:@//db-server:1521/orclpdb
怎么验证 tnsnames.ora 是否生效？别信“OK”，要看三行关键输出
tnsping 是唯一能快速验证解析行为的工具，但它不测数据库是否真能登录——只管“名字能不能转成地址”和“监听器通不通”。
- 运行
tnsping 别名，重点看三行输出：
–Attempting to contact (DESCRIPTION=...)：确认解析出的HOST、PORT、PROTOCOL是否符合预期
–Used parameter files:：确认实际加载的是哪个tnsnames.ora（避免改了 A 文件却读了 B）
–Used TNSNAMES adapter to resolve the alias：说明确实用了该文件，而不是硬编码或 Easy Connect -
tnsping成功 ≠ 数据库可连：它不校验实例是否启动、用户密码是否正确、甚至不建立真实会话。真正验证要用sqlplus user/pass@别名或应用层真实连接 - 如果
tnsping报TNS-03505，优先检查文件路径、别名拼写、括号匹配；报TNS-12541，说明监听器没运行或防火墙拦了端口
最常被忽略的是：tnsnames.ora 文件权限（Linux/macOS 下需对 Oracle 用户可读），以及 Windows 中路径含空格或中文导致解析失败——哪怕内容完全正确，也白搭。
