Instant Client 下载和路径设置最关键：必须手动下载匹配版本的 Basic 和可选 SDK 包，解压至无空格无中文路径并配置 PATH 或 LD_LIBRARY_PATH；cx_Oracle 已重命名为 oracledb，推荐优先使用纯 Python 的 oracledb；连接时注意 service_name、密码 URL 编码及 Thin/Thick 模式区别；进程退出报 ORA-24550 时应显式关闭连接或用上下文管理器。
Instant Client 下载和路径设置最关键
Oracle 官方不提供 pip 安装的 Oracle 客户端，必须手动下载 Instant Client 并正确暴露给系统。Windows 用户最容易卡在这一步：下载错版本（比如下了 SDK 包却没下 Basic 包），或解压后没把路径加进 PATH 环境变量。
实操建议：
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 只下载 Basic（不是 Basic Light）和可选的 SDK（仅开发需要头文件时才下），版本必须与你的 Python 位数（32/64）和 Oracle 服务端兼容，推荐用
19.21或21.10这类长期支持小版本 - 解压到无空格、无中文的路径，例如
C:\oracle\instantclient_21_10 - 把该路径加进系统
PATH（Windows）或LD_LIBRARY_PATH（Linux/macOS），重启终端或命令行生效 - 验证是否成功：在终端运行
tnsping（如果 Instant Client 自带）或直接 Python 里执行import cx_Oracle不报DLL load failed就算过第一关
cx_Oracle 不能 pip install 的常见原因
从 8.3 版本起，cx_Oracle 已重命名为 oracledb，但很多老项目仍依赖旧版；而旧版 cx_Oracle 在 pip 安装时会尝试编译 C 扩展，若本地没装 Visual Studio 构建工具或 Instant Client 头文件（即 SDK），就会失败并报 failed building wheel 或 cannot find oci.h。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 优先用新库：
pip install oracledb—— 它纯 Python 实现，无需 Instant Client（基础模式），也无需编译，适合大多数查询场景 - 如果必须用
cx_Oracle（比如依赖 DB API 2.0 的老代码），就一定要先装好 Instant Client SDK，并确保OCI_INC_DIR和OCI_LIB_DIR环境变量指向 SDK 的include和lib\msvc目录 - Windows 下更稳妥的方式是下载对应 Python 版本和架构的
.whl文件（从 PyPI 页面 找），然后pip install xxx.whl
oracledb 连接字符串写法和权限陷阱
oracledb 默认启用 Thin 模式（无需 Instant Client），但连接字符串格式和权限要求容易出错。最典型的是用 Easy Connect 语法连不上，或者报 ORA-01017: invalid username/password 却确认密码没错。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 连接字符串格式统一用
"username/password@hostname:port/service_name"，注意不是sid（除非显式启用mode=oracledb.SYSDBA或使用cx_Oracle的旧 SID 方式） - Oracle 12c+ 默认创建的用户属于 PDB（可插拔数据库），service_name 必须填对，可用
SELECT value FROM v$parameter WHERE name = 'service_names';查 - 密码含特殊字符（如
@、/）时，必须 URL 编码，例如pass@123→pass%40123 - Thin 模式不支持外部认证（OS Auth）、高级安全选项（如 TDE），如需这些功能，必须切回 Thick 模式：
oracledb.init_oracle_client(lib_dir=r"C:\oracle\instantclient_21_10")
Python 进程退出时报 ORA-24550 错误
程序正常跑完，但解释器退出时突然抛 ORA-24550: signal received: Unknown signal，尤其多线程/异步环境下高频出现。这不是业务逻辑错误，而是 Oracle 客户端库在进程清理阶段收到未预期信号（常见于 Windows 上的 Ctrl+C 中断残留或线程未 clean shutdown）。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 确保所有
Connection和Cursor显式关闭：conn.close()，不要只靠 GC 回收 - 使用上下文管理器最安全：
with oracledb.connect(...) as conn: with conn.cursor() as cur: cur.execute("SELECT 1 FROM DUAL") - 多线程场景下，避免跨线程共享
Connection；每个线程用独立连接，或用连接池（oracledb.create_pool()） - 若仍报错且不影响结果，可在主程序末尾加
import os; os._exit(0)强制退出（仅调试用，生产慎用）
tnsping 和 sqlplus 确认网络和凭据通了再说。 
