CouchDB是面向文档的NoSQL数据库，以JSON存储、HTTP REST API访问，支持多主复制与离线优先，常用于区块链、同步方案及Celery结果后端等场景。
PHP 本身不提供原生 CouchDB 驱动，必须通过 HTTP 协议调用，配置核心就是确保 PHP 能发出去请求、CouchDB 在线且可认证、网络端口通。
确认 CouchDB 已独立安装并监听 5984 端口
CouchDB 不是 phpEnv 或 XAMPP 的一部分，不能靠 php.ini 启用扩展。你必须单独安装官方 MSI 包（如 apache-couchdb-3.3.3.msi），安装时勾选「Add to PATH」并设置管理员账号（如 admin/secret123）。
- 检查端口是否就绪：
netstat -ano | findstr :5984，应看到LISTENING状态，且 PID 对应erl.exe - 若无输出，说明服务未启动：打开 Windows 服务管理器，找
Apache CouchDB并启动它 - 若提示“地址已被占用”，常见于 Skype 或旧版 CouchDB，需关闭冲突程序或改 CouchDB 的
local.ini中port = 5984
PHP 代码直连验证：绕过所有 SDK 先测通路
别急着装 PHP-on-Couch 或 couchdb-php 类库——90% 的连接失败卡在基础 HTTP 层。用最简 curl 测试：
$url = 'http://admin:secret123@localhost:5984/';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_NOBODY, true);
curl_setopt($ch, CURLOPT_FAILONERROR, false);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($http_code === 200) {
echo "✅ 连通且认证成功";
} else {
echo "❌ HTTP {$http_code}: 检查 CouchDB 是否运行、凭据是否匹配、Windows 防火墙是否放行 5984";
}
- 返回
7（Failed to connect）→ 服务没起来，或127.0.0.1:5984未监听 - 返回
401→ 用户名密码错；MSI 安装默认不设管理员，必须在向导中手动填，否则仍是Admin Party模式（不安全，但会返回 200） - 返回
0→ 可能被杀毒软件拦截，或curl扩展未启用（检查phpinfo()中是否有cURL support => enabled）
Web 前端 JS 调用 CouchDB 时的 CORS 坑
如果 PHP 是后端代理，而前端用 fetch 直连 CouchDB，必须改 CouchDB 的 local.ini，否则浏览器会因预检失败阻断请求：
立即学习“PHP免费学习笔记（深入）”；
[chttpd] enable_cors = true [cors] origins = http://localhost:8080 credentials = true methods = GET,POST,PUT,DELETE,OPTIONS headers = accept,authorization,content-type,origin,x-requested-with
-
origins = *和credentials = true冲突，浏览器直接拒绝——必须写死前端地址，如http://localhost:8080或https://myapp.com - 改完重启 CouchDB 服务，否则配置不生效
- 若用 PHP 作反向代理（如 Nginx 把
/couchdb代理到http://localhost:5984），可完全规避 CORS，此时前端仍连自己域名
真正容易被忽略的是：CouchDB 的认证凭据必须出现在 URL 中（http://user:pass@...），且不能靠 Authorization header 在简单请求里传递——因为 GET 请求若带凭据 header，浏览器会强制触发 OPTIONS 预检，而 CouchDB 默认不处理带凭据的预检响应，除非你显式配好 cors 段并重启服务。
