从 Windows 迁移到 Mac 后使用 Navicat 通过 Oracle Wallet 连接 Oracle Cloud ATP/ADW 的踩坑记录。环境信息操作系统: macOS (Apple Silicon ARM64)Navicat: Premium 版本Oracle Instant Client: 23.26.1.0.0数据库: Oracle Cloud ATP (自治数据库)一、安装 Oracle Instant Client1.1 下载安装包从 Oracle 官网 下载以下三个 DMGinstantclient-basic-macos.arm64-23.26.1.0.0.dmginstantclient-sqlplus-macos.arm64-23.26.1.0.0.dmg可选instantclient-tools-macos.arm64-23.26.1.0.0.dmg可选注意: Navicat 连接只需要basic包sqlplus和tools是命令行工具可选安装。1.2 安装步骤双击 DMG 文件将instantclient_23_26文件夹拖拽到/usr/local/lib/目录。或通过命令行# 挂载 DMGhdiutil attach ~/Downloads/instantclient-basic-macos.arm64-23.26.1.0.0.dmg# 复制到系统目录sudocp-R/Volumes/instantclient-basic-23.26.1.0.0/instantclient_23_26 /usr/local/lib/# 卸载 DMGhdiutil detach /Volumes/instantclient-basic-23.26.1.0.01.3 配置环境变量编辑~/.zshrc# Oracle Instant ClientexportORACLE_HOME/usr/local/lib/instantclient_23_26exportDYLD_LIBRARY_PATH$ORACLE_HOME:$DYLD_LIBRARY_PATHexportPATH$ORACLE_HOME:$PATH# Wallet 配置exportTNS_ADMIN$HOME/oracle_wallet生效配置source~/.zshrc1.4 验证安装ls$ORACLE_HOME/libclntsh.dylib# 输出: /usr/local/lib/instantclient_23_26/libclntsh.dylib二、准备 Wallet 文件2.1 获取 WalletOracle Cloud ATP/ADW: 登录 Oracle Cloud 控制台 → 数据库详情 → Download Wallet公司自建数据库: 联系 DBA 提供2.2 解压 Walletmkdir-p~/oracle_walletcd~/oracle_walletunzip~/Downloads/Wallet_*.zip解压后应包含以下文件~/oracle_wallet/ ├── cwallet.sso # Wallet 主文件 ├── cwallet.sso.lck ├── ewallet.p12 # Wallet 密钥库 ├── ewallet.p12.lck ├── ewallet.pem ├── keystore.jks ├── ojdbc.properties ├── README ├── sqlnet.ora # 网络配置 ├── tnsnames.ora # TNS 别名配置 └── truststore.jks2.3 检查 sqlnet.ora确保包含 Wallet 路径配置WALLET_ROOT/Users/你的用户名/oracle_wallet SSL_CLIENT_AUTHENTICATIONFALSE三、配置 Navicat3.1 设置 OCI 环境Navicat → 偏好设置 → 环境参数值Oracle Home/usr/local/lib/instantclient_23_26OCI Library/usr/local/lib/instantclient_23_26/libclntsh.dylib重要: 修改后必须完全退出 NavicatCmdQ再重新打开。3.2 复制 Wallet 到 Instant Client 目录这是最关键的一步Navicat 会从 Instant Client 的network/admin目录读取 Wallet 文件而不是从TNS_ADMIN环境变量指向的位置。# 创建目录sudomkdir-p/usr/local/lib/instantclient_23_26/network/admin# 复制所有 Wallet 文件sudocp~/oracle_wallet/cwallet.sso /usr/local/lib/instantclient_23_26/network/admin/sudocp~/oracle_wallet/ewallet.p12 /usr/local/lib/instantclient_23_26/network/admin/sudocp~/oracle_wallet/ewallet.pem /usr/local/lib/instantclient_23_26/network/admin/sudocp~/oracle_wallet/keystore.jks /usr/local/lib/instantclient_23_26/network/admin/sudocp~/oracle_wallet/truststore.jks /usr/local/lib/instantclient_23_26/network/admin/sudocp~/oracle_wallet/tnsnames.ora /usr/local/lib/instantclient_23_26/network/admin/sudocp~/oracle_wallet/sqlnet.ora /usr/local/lib/instantclient_23_26/network/admin/# 修复权限重要sudochown-R$(whoami)/usr/local/lib/instantclient_23_26/network/admin/chmod600/usr/local/lib/instantclient_23_26/network/admin/*.ssochmod600/usr/local/lib/instantclient_23_26/network/admin/*.p123.3 新建连接连接 → Oracle参数值连接方式TNS网络服务名tnsnames.ora中的别名如DBNAME_MEDIUM用户名数据库用户名密码数据库密码注意: 网络服务名只填别名不要填完整的(DESCRIPTION...)字符串。四、常见错误及解决4.1 ORA-12154: Cannot find alias原因: Navicat 找不到tnsnames.ora或别名不存在。解决:确认tnsnames.ora已复制到/usr/local/lib/instantclient_23_26/network/admin/确认填的是别名如DBNAME_MEDIUM不是完整描述字符串4.2 ORA-12506: TNS:listener rejected connection based on service ACL filtering原因: IP 地址不在数据库访问白名单中。解决:在 Oracle Cloud 控制台 → Network → Access Control List 中添加你的公网 IP或联系 DBA 添加 IP 白名单4.3 ORA-28759: failure to open file原因: Wallet 文件cwallet.sso、ewallet.p12找不到或权限不足。解决:确认 Wallet 文件已复制到network/admin/目录确认文件权限为当前用户可读写chmod 600 *.sso *.p124.4 java: JDK isn’t specified for module原因: IDEA 未配置 JDK。解决: File → Project Structure → SDK → 选择已安装的 JDK。4.5 java: 找不到符号 builder()原因: Lombok 注解处理未启用。解决:安装 Lombok 插件Preferences → Compiler → Annotation Processors → 勾选 Enable确认pom.xml中配置了annotationProcessorPaths五、完整环境变量配置# ~/.zshrc# Oracle Instant ClientexportORACLE_HOME/usr/local/lib/instantclient_23_26exportDYLD_LIBRARY_PATH$ORACLE_HOME:$DYLD_LIBRARY_PATHexportPATH$ORACLE_HOME:$PATHexportTNS_ADMIN$HOME/oracle_wallet# Maven可选exportMAVEN_OPTS-Xmx1024m六、总结从 Windows 迁移到 Mac 后Oracle Wallet 连接的核心要点Instant Client 必须安装且版本与数据库匹配Wallet 文件必须复制到network/admin/目录Navicat 不会读取TNS_ADMIN环境变量文件权限必须正确特别是cwallet.sso和ewallet.p12Navicat 修改 OCI 配置后必须重启网络服务名只填别名不要填完整连接字符串希望这篇指南能帮你少走弯路如有问题欢迎留言讨论。