node-oracledb必须配合oracle instant client才能工作，跳过安装会导致编译失败或运行时libclntsh.so not found等错误；linux需下载basic和sdk zip包并配置ldconfig，macos推荐brew安装，windows需将解压路径加入path。
node-oracledb 不是纯 JavaScript 驱动，必须配合 Oracle Instant Client 才能工作。跳过这步直接 npm install oracledb 会编译失败，或运行时报 ORA-12154: TNS:could not resolve the connect identifier 或更底层的 libclntsh.so not found 错误。
安装 Oracle Instant Client 是硬性前提
无论你用 Ubuntu、CentOS 还是 macOS，node-oracledb 都依赖 Oracle 官方提供的二进制客户端库。它不打包进 npm 包，也不能靠 apt install 或 brew install 一键解决。
- Linux（如 Ubuntu/Debian）：下载
instantclient-basic-linux.x64-和instantclient-sdk-linux.x64-的 ZIP 包（版本建议 21.10 或 23.5，与你的 Oracle DB 版本兼容即可），解压到固定路径（如/opt/oracle/instantclient_21_10） - macOS：用
brew tap oracle/homebrew-instantclient+brew install instantclient-basic instantclient-sdk更稳妥；若手动下载 ZIP，需执行sudo installer -pkg instantclient-*.pkg -target / - Windows：下载对应位数的
instantclient-basic-windows.x64-ZIP，解压后把路径加进系统PATH环境变量
完成后验证：ldd node_modules/oracledb/build/Release/oracledb.node | grep libclntsh（Linux）或 otool -L node_modules/oracledb/build/Release/oracledb.node | grep libclntsh（macOS）应能定位到库文件。
ORACLE_HOME 和 LD_LIBRARY_PATH 不是必须设的
很多老教程强调设置 ORACLE_HOME，但 node-oracledb 从 v5 开始默认不读这个变量。真正关键的是让动态链接器能找到 libclntsh.so（Linux）或 libclntsh.dylib（macOS）。
- Linux：推荐用
ldconfig -n /opt/oracle/instantclient_21_10临时注册，或写入/etc/ld.so.conf.d/oracle.conf后运行ldconfig - macOS：确保
instantclient_*.zip解压后libclntsh.dylib在~/lib或/usr/local/lib，或通过export DYLD_LIBRARY_PATH=/opt/oracle/instantclient_21_10（仅开发时） - Node.js 进程启动前环境变量必须生效——用
pm2 start app.js --env production时，pm2不自动继承 shell 的DYLD_LIBRARY_PATH，得显式传入
安装 oracledb 时要避开常见编译陷阱
npm install oracledb 实际会触发原生模块编译。失败往往不是代码问题，而是构建链缺失。
- 确保已装
python3（非 Python 2）且在$PATH中；node-gyp依赖它 - Ubuntu/Debian 需提前运行：
sudo apt-get install build-essential python3 libaio-dev - macOS 需 Xcode 命令行工具：
xcode-select --install - 如果反复报
gyp ERR! stack Error: spawn make ENOENT，说明make没装或不在路径里 - CI/CD 环境（如 GitHub Actions）中，Instant Client 路径需和本地一致，否则
npm install会静默跳过编译，导致 runtime error
连接字符串里的 connectString 容易写错格式
oracledb.getConnection({ user, password, connectString }) 中的 connectString 不是随便拼的 host:port/service_name。
- 最简形式：
"localhost:1521/XE"（适用于 Oracle XE 默认配置） - 标准 TNS 格式：
"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XE)))" - 如果用 Oracle Wallet 或连接云数据库（如 ADB），
connectString应为 wallet 路径或云服务提供的完整连接串，不能省略/?wallet_location=...参数 - 密码含特殊字符（如
@、/）时，URL 形式连接串必须对它们做encodeURIComponent()，否则解析失败
一个容易被忽略的点：Oracle 21c+ 默认启用 TLS 加密，若服务端未配证书，客户端需显式加 ssl: false 到连接选项，否则卡在 handshake。
