ld_library_path易失效因作用域窄且加载顺序敏感；推荐用ldconfig系统级注册instant client路径，并配对设置oracle_home与tns_admin，同时安装libaio1依赖。
直接设 ld_library_path 是最常见、也最容易出错的做法——它能快速让 sqlplus 或 cx_oracle 跑起来，但一旦路径写错、版本混用或用户环境未生效，就会报 libclntsh.so: cannot open shared object file 或更隐蔽的 ora-12705。
为什么 LD_LIBRARY_PATH 常失效？
根本原因不是变量没设，而是加载顺序和作用域问题：
-
LD_LIBRARY_PATH只影响当前 shell 及其子进程；systemd服务、GUI 应用（如 VS Code 终端）、cron 任务默认不继承它 - 若多个 Oracle 版本共存（比如
instantclient_19_8和instantclient_21_10），路径顺序错一位，就可能加载旧版.so导致符号冲突 - Ubuntu 22.04+ 默认使用
systemd --user，~/.bashrc里的 export 对 GUI 启动的 Python 进程无效
推荐做法：用 ldconfig 注册系统级库路径
比反复改 LD_LIBRARY_PATH 更可靠，尤其适合生产环境或需要多用户/多进程调用的场景：
- 解压 Instant Client 到固定位置，例如
/opt/oracle/instantclient_21_10 - 创建软链接统一入口：
sudo ln -sf /opt/oracle/instantclient_21_10 /opt/oracle/instantclient - 写入系统库配置：
echo "/opt/oracle/instantclient" | sudo tee /etc/ld.so.conf.d/oracle.conf - 刷新缓存：
sudo ldconfig - 验证是否注册成功：
ldconfig -p | grep libclntsh—— 应看到类似libclntsh.so.21.1 (libc6,x86-64) => /opt/oracle/instantclient/libclntsh.so.21.1
ORACLE_HOME 和 TNS_ADMIN 必须配对设
只设 LD_LIBRARY_PATH 或只设 ORACLE_HOME 都不够。很多工具（如 sqlplus、cx_Oracle）会按顺序查找 tnsnames.ora，路径逻辑是：
- 先看
TNS_ADMIN环境变量指向的目录 - 没设则 fallback 到
$ORACLE_HOME/network/admin - 两者都未设，才查当前目录或
$HOME
所以至少要配这对：
export ORACLE_HOME=/opt/oracle/instantclient export TNS_ADMIN=$ORACLE_HOME/network/admin
然后手动建目录：mkdir -p $TNS_ADMIN，再放 tnsnames.ora。别指望 ORACLE_HOME 自动创建 network/admin。
调试时必跑的三行命令
遇到 “找不到库” 或 “连接失败”，别猜，直接执行：
-
ldd $(which sqlplus) | grep clnt—— 看sqlplus实际链接的是哪个libclntsh.so -
strace -e trace=openat sqlplus /nolog 2>&1 | grep -i tns—— 查它到底去哪找tnsnames.ora -
echo $LD_LIBRARY_PATH; echo $ORACLE_HOME; echo $TNS_ADMIN—— 确认当前 shell 环境变量真实值（注意：不是~/.bashrc里写的，是已生效的）
真正容易被忽略的点：Ubuntu 上 libaio1 是硬依赖，不装它，libclntsh.so 即便路径对也会加载失败，错误表现却像路径问题。装它：sudo apt install libaio1。
