Mac M1安装oci8扩展后Nginx返回502 Bad Gateway问题求助
Apple M1设备PHP oci8扩展架构兼容问题解决方案
问题背景
测试环境
- 设备:Apple M1芯片 MacBook Pro
- 测试PHP版本:
➜ project-name php --version PHP 7.4.16 (cli) (built: Mar 4 2021 12:36:48) ( NTS ) Copyright (c) The PHP Group Zend Engine v3.4.0, Copyright (c) Zend Technologies with Zend OPcache v7.4.16, Copyright (c), by Zend Technologies
➜ ~ php --version PHP 8.0.7 (cli) (built: Jun 3 2021 19:10:37) ( NTS ) Copyright (c) The PHP Group Zend Engine v4.0.7, Copyright (c) Zend Technologies with Zend OPcache v8.0.7, Copyright (c), by Zend Technologies
- 测试过的Oracle Instant Client及SDK版本:
- v11.1
- v12.2
- v19.8.0.0.0
操作流程
CLI下运行composer require yajra/laravel-oci8:^7验证oci8运行正常:
➜ project-name pa package:discover --ansi Discovered Package: facade/ignition Discovered Package: fideloper/proxy Discovered Package: fruitcake/laravel-cors Discovered Package: laravel/tinker Discovered Package: nesbot/carbon Discovered Package: nunomaduro/collision Discovered Package: yajra/laravel-oci8 Package manifest generated successfully.
oci8安装步骤如下:
- 解压Oracle安装包(instant、sdk、sqlplus)后执行软链接操作:
sudo ln -s /opt/instantclient_19_8/sdk/include/*.h /usr/local/include/ sudo ln -s /opt/instantclient_19_8/sqlplus /usr/local/bin/ sudo ln -s /opt/instantclient_19_8/*.dylib /usr/local/lib/ sudo ln -s /opt/instantclient_19_8/*.dylib.19.1 /usr/local/lib/ sudo ln -s /usr/local/lib/libocci.dylib.19.1 /usr/local/lib/libocci.dylib sudo ln -s /usr/local/lib/libclntsh.dylib.19.1 /usr/local/lib/libclntsh.dylib
- 执行
sudo pecl install oci8-2.2.0安装PHP7.4对应版本,PHP8版本安装对应适配的oci8扩展,安装时oracle home参数填写为instantclient,/usr/local/lib,安装成功返回信息如下:
Build process completed successfully Installing '/opt/homebrew/Cellar/php@7.4/7.4.16/pecl/20190902/oci8.so' install ok: channel://pecl.php.net/oci8-2.2.0 Extension oci8 enabled in php.ini
- PHP7.4版本修改extension_dir配置:
extension_dir = "/opt/homebrew/Cellar/php@7.4/7.4.16/pecl/20190902" ;extension_dir = "/opt/homebrew/lib/php/20190902"
PHP8版本无需修改该配置。
验证Nginx配置正常:
➜ ~ sudo nginx -t nginx: the configuration file /opt/homebrew/etc/nginx/nginx.conf syntax is ok nginx: configuration file /opt/homebrew/etc/nginx/nginx.conf test is successful
故障表现
- web访问
phpinfo()时,页面返回502 Bad Gateway nginx/1.19.8,调用oci_error()返回false无错误提示。 - 注释
php.ini中的;extension=oci8.so后执行brew services restart php@7.4,phpinfo()可正常访问,但无法使用oci_connect函数。 - 重启设备、Nginx和PHP服务均未解决问题,Nginx和Valet日志无相关错误记录,日志路径如下:
/usr/local/var/log/nginx /opt/nginx/logs/error.log
- 执行oci连接测试代码:
<?php if (oci_connect('xusername', 'xpassword', 'xip/XE', 'xcharset')) { print 'right'; } else { print 'error'; }
CLI返回报错:
➜ oracle php -q b.php dyld: lazy symbol binding failed: Symbol not found: _OCIEnvNlsCreate Referenced from: /opt/homebrew/lib/php/pecl/20200930/oci8.so Expected in: flat namespace dyld: Symbol not found: _OCIEnvNlsCreate Referenced from: /opt/homebrew/lib/php/pecl/20200930/oci8.so Expected in: flat namespace [1] 35993 abort php -q b.php
- 尝试使用PPC架构的
instantclient-sqlplus-macosx-10.1.0.3版本后,phpinfo()可正常加载oci8配置表,执行php -i无_OCIClientVersion符号报错,但连接测试仍报_OCIEnvNlsCreate符号找不到错误。
故障根因
Oracle官方暂未提供ARM架构的macOS Instant Client安装包,仅支持Intel x86和PPC架构,ARM架构下原生运行的PHP无法兼容x86架构的OCI动态库,导致符号绑定失败。
可用解决方案
方案一:Rosetta 2模拟运行x86全栈
- 右键点击终端应用,选择「显示简介」,勾选「使用Rosetta打开」,重启终端。
- 安装x86版本的Homebrew,再使用x86版本的brew重新安装PHP、Nginx等相关服务,按照原流程安装Oracle Instant Client和oci8扩展,所有组件均运行在x86模拟环境下即可正常调用。
方案二:Docker容器部署
拉取x86架构的PHP官方镜像,在容器内安装Oracle Instant Client和oci8扩展,将服务端口映射到本地使用,完全避开本地架构兼容问题,适合开发和生产环境通用。
临时替代方案
本地开发场景可使用纯PHP实现的Oracle客户端类库替代扩展,无需依赖系统OCI动态库,但功能受限,不建议生产环境使用。
内容的提问来源于stack exchange,提问作者yogithesymbian
相关产品推荐
相关产品推荐

