windows上使用node-oracledb Thick 模式连接 Oracle 11g

连接 Oracle 11g 时，必须使用 Thick 模式。

Oracle 11g 是一个相对较早的版本，而 node-oracledb 默认的 Thin 模式（纯 JavaScript 实现）只支持 Oracle 数据库 12.1 或更高版本。连接 11g 会引发 NJS-138 错误，提示该版本在 Thin 模式下不受支持。因此，必须切换到功能更全面、兼容性更好的 Thick 模式。

---

🛠️ Windows 下启用 Thick 模式的详细步骤

1️⃣ 第一步：安装 Oracle Instant Client

Thick 模式需要通过 Oracle 的本地客户端库来通信，最简单的方式就是下载并安装 Oracle Instant Client。

• 下载：访问 Oracle Instant Client 下载页，选择与你的操作系统匹配的 Basic 或 Basic Light 版本。需要注意，Windows 版通常有 32 位和 64 位之分，请确保与你安装的 Node.js 版本位数一致。如果数据库版本是 11g，选择 Instant Client 11.2 或更高版本即可。

• 解压：将下载的 ZIP 文件解压到一个你容易找到的路径，例如 C:\oracle\instantclient_19_14。

• 配置环境变量：将这个解压路径添加到系统的 PATH 环境变量中，以便系统能找到这些库文件。

  手动设置 PATH 的方法：

  1. 在 Windows 搜索栏输入“环境变量”，选择“编辑系统环境变量”。
  2. 在弹出的窗口中点击“环境变量”。
  3. 在“系统变量”列表中找到 Path 变量，选中后点击“编辑”。
  4. 点击“新建”，将你的 Instant Client 路径（例如 C:\oracle\instantclient_19_14）粘贴进去，然后一直点击“确定”保存。

2️⃣ 第二步：编写代码启用 Thick 模式

在 Node.js 代码中，你需要在建立任何数据库连接之前调用 oracledb.initOracleClient() 函数，并指定客户端库的路径。如果你的环境变量设置正确，libDir 选项可以省略。

// 引入 node-oracledb 模块
const oracledb = require('oracledb');

// 1. 初始化 Oracle 客户端，启用 Thick 模式
// 推荐在应用启动时调用一次
try {
    // 如果 Instant Client 已正确配置在 PATH 中，可以省略 libDir 参数
    // 如果未配置 PATH，则需要显式指定路径，注意 Windows 路径中的反斜杠需要转义
    // oracledb.initOracleClient({ libDir: 'C:\\oracle\\instantclient_19_14' });
    oracledb.initOracleClient(); 
    console.log('Thick 模式已启用');
} catch (err) {
    console.error('初始化 Oracle 客户端失败:', err);
    process.exit(1);
}

// 2. 配置数据库连接参数
const dbConfig = {
    user: 'your_username',        // 替换为你的数据库用户名
    password: 'your_password',    // 替换为你的数据库密码
    connectString: 'hostname:port/service_name' // 替换为你的数据库连接字符串
};

// 3. 连接数据库
async function run() {
    let connection;
    try {
        connection = await oracledb.getConnection(dbConfig);
        console.log('成功连接到 Oracle 数据库 (Thick 模式)');

        // 执行你的数据库操作
        // const result = await connection.execute(`SELECT 'Hello, Oracle!' FROM DUAL`);
        // console.log(result.rows);

    } catch (err) {
        console.error('数据库连接失败:', err);
    } finally {
        if (connection) {
            try {
                await connection.close();
                console.log('数据库连接已关闭');
            } catch (err) {
                console.error('关闭连接失败:', err);
            }
        }
    }
}

run();

💡 常见问题与排查

1. DPI-1047: Cannot locate Oracle Client library：这个错误最常见，表示 Node.js 找不到 Oracle 客户端库。请确认 Instant Client 的路径已正确添加到系统 PATH 环境变量中，并重启了命令行或终端。
2. NJS-045: cannot load a node-oracledb Thick mode binary：通常是因为 Node.js 的位数（32/64 位）与 Instant Client 的位数不匹配，请重新下载并安装对应位数的版本。
3. NJS-138: connections to this database server version are not supported...：如果在 Thin 模式下遇到此错误，说明你尚未切换到 Thick 模式。请确认你是否在代码中正确调用了 initOracleClient()。
4. 数据库密码验证错误：如果 Thick 模式配置正确但仍无法连接，可能是数据库密码的哈希算法过旧（例如从 10g 时代遗留的密码）。一种快速的解决方法是重置该数据库用户的密码，这通常会使用更新、更标准的算法来重新哈希密码，从而解决问题。

参考链接

https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html#installing-node-js-and-node-oracledb-on-microsoft-windows
https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#enablingthick