能连上 Oracle 数据库的关键是 DYLD_LIBRARY_PATH、TNS_ADMIN 和符号链接三者对齐；需按 Mac 架构下载对应 Instant Client，手动建立无版本号的 dylib 软链接，TNS_ADMIN 必须指向含 network/admin 的完整路径，并在 ~/.zshrc 中正确配置环境变量后 source 生效。
能连上 Oracle 数据库，关键不是装了几个包，而是 DYLD_LIBRARY_PATH、TNS_ADMIN 和符号链接这三件事是否对齐。 macOS 上装 Instant Client 失败，90% 是环境变量没生效或 dylib 找不到，不是下载错了版本。
确认你的 Mac 架构再下载对应包
终端执行：uname -m。输出 arm64（M1/M2/M3/M4）就去下 ARM64 版；输出 x86_64（Intel）才用 Intel x86 版。官网两个架构的 DMG/ZIP 是分开发布的，混用会报 mach-o, but wrong architecture 错误。
- ARM64 下载页：Oracle 官网搜 “Instant Client for macOS (ARM64)”
- Intel 下载页：搜 “Instant Client for macOS (Intel x86)”
- 至少要下
instantclient-basic-macos.x64-*.zip（或 arm64 对应版）和instantclient-sqlplus-macos.x64-*.zip - 如果后续要用 Python（cx_Oracle / oracledb）或 PHP（oci8），还得加
instantclient-sdk-macos.x64-*.zip
解压后必须手动建立符号链接
macOS 不像 Linux 默认找 /usr/lib，也不自动解析版本号后缀的 dylib（如 libclntsh.dylib.19.1）。Instant Client 解压后目录里一堆带版本号的 .dylib，但 sqlplus 或程序运行时只认无版本号的名，比如 libclntsh.dylib。
- 进到解压出的目录，例如
/opt/oracle/instantclient_19_8 - 执行：
ln -s libclntsh.dylib.19.1 libclntsh.dylib - 同样处理：
ln -s libocci.dylib.19.1 libocci.dylib、ln -s libnnz19.dylib libnnz19.dylib - 如果之后遇到
Library not loaded: libclntsh.dylib，说明漏建了某个链接 —— 直接ls -l lib*.dylib看哪些是 broken link
TNS_ADMIN 必须指向含 tnsnames.ora 的完整路径
很多人把 tnsnames.ora 放在解压目录根下就以为够了，但 Instant Client 只在 TNS_ADMIN 指向的 network/admin 子目录里找它 —— 不是“当前目录”，也不是“任意位置”。
- 手动创建：
mkdir -p /opt/oracle/instantclient_19_8/network/admin - 把
tnsnames.ora放进去，内容格式不能少括号和等号，例如：ORCL = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.1.100)(PORT = 1521)) (CONNECT_DATA = (SERVICE_NAME = ORCL))) - 环境变量设为：
export TNS_ADMIN=/opt/oracle/instantclient_19_8/network/admin（注意：结尾不加/admin，TNS_ADMIN值就是admin所在的父目录） - 验证：
echo $TNS_ADMIN+ls $TNS_ADMIN/tnsnames.ora
环境变量加载顺序和 shell 类型容易失效
macOS 新系统默认用 zsh，但很多教程还写 .bash_profile。如果你改了 .bash_profile 却新开终端没生效，大概率是因为 shell 没读它。
- 先查当前 shell：
echo $SHELL—— 输出/bin/zsh就该改~/.zshrc，不是.bash_profile - 在
~/.zshrc里写（路径按你实际解压位置替换）：export ORACLE_HOME=/opt/oracle/instantclient_19_8export DYLD_LIBRARY_PATH=$ORACLE_HOMEexport TNS_ADMIN=$ORACLE_HOME/network/adminexport PATH=$ORACLE_HOME:$PATH - 改完执行：
source ~/.zshrc，再开新终端也得重新source一次才能继承（除非你把它写进启动文件） - 验证：
sqlplus /nolog能进交互界面，再connect user/pass@ORCL才算真正通
最常被跳过的细节：tnsnames.ora 文件权限必须是用户可读（chmod 644），且文件里不能有 Windows 风格换行（\r\n）；DYLD_LIBRARY_PATH 如果指向了空目录或拼错路径，sqlplus 启动时不会报错，但一连数据库就卡住或闪退 —— 这时候看 otool -L $(which sqlplus) 才能发现 dylib 路径是 not found。
