OCI库加载失败主因是动态链接器未被告知libclntsh.so路径，需正确设置LD_LIBRARY_PATH或/etc/ld.so.conf.d/oracle.conf；版本需向下兼容（如19c客户端可连12.1+数据库）；tnsnames.ora由TNS_ADMIN指定路径；Windows下需确保所有DLL同目录且位数匹配。
OCI 库找不到：libclntsh.so 加载失败的典型表现
运行 oci 程序时抛出 error while loading shared libraries: libclntsh.so: cannot open shared object file，说明系统能定位到你的程序，但找不到 oracle 客户端核心库。这不是权限问题，也不是编译没链接，而是动态链接器压根没被告诉去哪找 libclntsh.so。
常见诱因是只解压了 Instant Client，没设置 LD_LIBRARY_PATH，或设置了却指向了错的目录（比如指向 instantclient_19_20 但实际解压的是 instantclient_19_19）。
- 确认
libclntsh.so确实存在：ls -l /path/to/instantclient_19_19/libclntsh.so*—— 注意带版本号的软链接是否指向真实文件 - 临时生效：执行
export LD_LIBRARY_PATH=/path/to/instantclient_19_19:$LD_LIBRARY_PATH，再跑程序验证 - 永久生效不要硬写进
/etc/ld.so.conf；改用/etc/ld.so.conf.d/oracle.conf写入路径，再运行sudo ldconfig - 如果用 Docker，必须在
Dockerfile中用ENV LD_LIBRARY_PATH /instantclient:$LD_LIBRARY_PATH，且确保 COPY 路径与环境变量一致
Instant Client 版本和 Oracle 数据库版本不匹配会怎样
Instant Client 不需要和数据库完全同版本，但有向下兼容边界：19c 的客户端能连 12.1+ 的库，但不能连 11g；21c 客户端默认不支持连接 12.1 以下的 DB，除非显式启用旧协议（需额外配置 sqlnet.ora）。
最稳妥的做法是选「等于或略高于」目标数据库主版本的客户端。例如连 Oracle Database 19c (19.21)，用 instantclient-basic-linux.x64-19.21.0.0.0dbru.zip 最省心。
- 下载页注意区分
Basic（含 OCI、OCCI）、SDK（头文件 +oci.h）、SQL*Plus（调试用，非必需） -
basic包里没有libocci.so—— 那是 C++ 封装库，得单独下basiclite或devel包才带 - ARM64（如 M1/M2 Mac 或 aarch64 Linux）必须下标
arm64的包，x86_64 包在 ARM 上直接报cannot execute binary file
Linux 下 tnsnames.ora 放哪、怎么让 OCI 找到它
OCI 默认不读当前目录下的 tnsnames.ora，它按固定顺序查：先看 TNS_ADMIN 环境变量指向的目录；没设就查 $ORACLE_HOME/network/admin；都不存在才 fallback 到 /etc/oracle/network/admin。
所以最轻量做法就是设 TNS_ADMIN，而不是去动 ORACLE_HOME（Instant Client 本来就不需要它）。
- 把
tnsnames.ora放进/opt/oracle/tns，然后export TNS_ADMIN=/opt/oracle/tns - 文件内别用中文或特殊字符做 alias 名；host 值别写成
localhost—— 容器或远程 DB 场景下很可能不通，换成具体 IP 或可解析域名 - 测试连通性优先用
sqlplus64（如果有），命令是sqlplus64 user/pass@MYDB，比写 C 程序快得多 - 若用 Go 的
godror或 Python 的cx_Oracle，它们底层也走 OCI，同样受TNS_ADMIN控制，不是各自实现一套解析逻辑
Windows 上 DLL 加载失败：为什么 oci.dll 找得到却报“找不到指定模块”
错误信息是 The specified module could not be found，但 oci.dll 明明在 PATH 里 —— 实际上是它依赖的其他 DLL（比如 orannzsbb19.dll、oraocci19.dll）缺失或版本不匹配。
Instant Client for Windows 是 zip 包，解压后所有 DLL 必须在同一个目录，不能拆开放；且 32/64 位严格分离：你的程序是 x64，就必须用 x64 的 client，混用必崩。
- 用
Dependencies.exe（开源工具）打开oci.dll，看红色标记的缺失模块，再检查对应 DLL 是否在同目录 - 不要把 Instant Client 目录加进系统 PATH；改为在程序启动前用脚本临时追加：
set PATH=C:\oracle\instantclient_19_19;%PATH% - Visual Studio 编译 C/C++ 程序时，Linker → Input → Additional Dependencies 里填
oci.lib，但运行时仍要靠 DLL 路径，.lib 只用于编译期符号解析 - 如果用了 Oracle Wallet，确保
sqlnet.ora里WALLET_LOCATION路径是绝对路径，且 wallet 文件夹里有cwallet.sso和ewallet.p12两个文件
