PHP连接CouchDB本质是HTTP请求而非数据库连接，需用cURL等发RESTful请求，注意Basic/JWT认证、JSON编码、Content-Type设置及\_rev字段管理。
PHP 连 CouchDB 用的是 HTTP 接口，不是传统数据库扩展
CouchDB 没有原生 PHP 扩展（比如 mysqli 或 pdo_pgsql 那种），它只暴露 RESTful HTTP API。所以 PHP 连 CouchDB 的本质是「发 HTTP 请求」，不是「建立数据库连接」。别找 ext-couchdb 或试图用 PDO 直连——不存在。
- 必须用
cURL、file_get_contents()（配合stream_context_create()）或现代 HTTP 客户端如guzzlehttp/guzzle - 认证方式通常是 Basic Auth（用户名密码 Base64 编码）或 JWT（若启用了插件）
- 所有操作都对应 HTTP 方法：
GET /db查库，PUT /db创建库，POST /db插入文档，GET /db/doc_id读文档
最简可行：用 cURL 发 GET 请求检查连通性
先确认网络和认证是否通，比写完整 CRUD 更关键。下面这段代码能快速验证：
$url = 'http://admin:password@localhost:5984/';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($http_code === 200) {
$info = json_decode($response, true);
echo "CouchDB 版本：" . ($info['version'] ?? 'unknown');
} else {
echo "HTTP 错误：" . $http_code;
}
- URL 中的
admin:password是管理员凭据；若未设管理员，请先运行curl -X PUT http://localhost:5984/_config/admins/admin -d '"password"' - 返回非 200 时，常见原因：CouchDB 服务没起来（
systemctl status couchdb）、端口被占、防火墙拦截、凭据错误 - 不要跳过这步直接写插入逻辑——很多「连不上」问题其实卡在基础 HTTP 层
插入/查询文档时注意 JSON 编码与 Content-Type
CouchDB 对请求体格式敏感，PHP 默认不自动设置 Content-Type: application/json，也不自动 JSON 编码数组，漏掉任一都会导致 400 或 415 错误。
- 插入文档必须用
POST或PUT，且 body 是纯 JSON 字符串（不是 PHP 数组） - 必须显式设置 header：
Content-Type: application/json和Accept: application/json - 用
json_encode($data, JSON_UNESCAPED_UNICODE)避免中文变 \uXXXX - 文档 ID 若用
PUT /db/doc_id方式插入，需确保doc_id符合 URL 安全规则（不能含空格、斜杠等）
PHP 处理 CouchDB 返回的 _rev 字段容易出错
每次更新文档，CouchDB 强制要求提供当前 _rev 值，否则返回 409 Conflict。PHP 里常有人忽略这个字段，导致「明明改了数据却没生效」。
立即学习“PHP免费学习笔记（深入）”；
- 读文档后，务必保存返回的
_rev字段（它在响应 JSON 顶层，和_id同级） - 修改后再发
PUT时，要把整个文档（含原_id和新_rev）一起提交 - 不要手动拼接
_rev，也不要从旧缓存里取——它随每次写入变化，过期即失效 - 批量更新时，每个文档的
_rev必须单独获取，不能复用
这个机制是 CouchDB MVCC 的核心，绕不开。写错一次，就卡在 409 里反复调试半天。
