phpEnv 不支持 ClickHouse，需作为独立服务部署；连接失败主因是端口、认证、白名单配置不当；PHP 调用推荐 HTTP 接口（8123 端口）或 smi2/phpclickhouse 库（9000 端口），大数据写入须分块且限批 ≤5000 行。

phpEnv 本身不支持 ClickHouse —— 它是为 PHP 开发环境设计的轻量级多版本管理工具（类似 pyenv 或 rbenv），只管 PHP 解释器、扩展和 CLI 工具链，不提供数据库服务安装或管理能力。

想在 Windows 或 macOS 上用 phpEnv 配合 ClickHouse 做大数据分析，必须把 ClickHouse 当作独立外部服务来对接，不能指望 phpEnv 启动它、配置它或自动集成它。

---

clickhouse-client 命令行连接失败：端口、用户、白名单三要素缺一不可

常见报错如：Code: 210. DB::NetException: Connection refused 或 Code: 192. Authentication failed，基本都卡在这三点：

• clickhouse-server 必须已启动且监听非 localhost 地址（默认只绑 127.0.0.1:9000）
  检查 /etc/clickhouse-server/config.xml 中的 <listen_host></listen_host>，改成 0.0.0.0 或具体内网 IP
• 用户密码未生效：修改 /etc/clickhouse-server/users.xml 后，必须重启服务
  sudo service clickhouse-server restart（Linux）或 brew services restart clickhouse（macOS via Homebrew）
• 远程客户端（比如你本地 Windows 上跑的 PHP 脚本）IP 不在白名单里
  在 users.xml 的对应用户段加：<networks><ip>::/0</ip></networks>（仅测试用），生产环境请精确到 CIDR 段

---

PHP 调用 ClickHouse 的两种可行路径：HTTP 接口 vs TCP 客户端

ClickHouse 原生不提供 PHP 扩展，所以必须走协议层：

立即学习“PHP免费学习笔记（深入）”；

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• HTTP 接口（推荐初学者）

  • 默认开启，端口 8123，无需额外配置认证（除非显式关掉）
  • 直接用 file_get_contents 或 cURL 发 POST 请求：

    curl -X POST "http://localhost:8123/?query=SELECT%20count()%20FROM%20system.tables"

  • 注意 URL 编码查询语句，Content-Type: text/plain，响应默认是 TSV

• TCP 协议（需第三方库）

  • 官方不维护 PHP driver，社区主流用 smi2/phpclickhouse
  • 安装：composer require smi2/phpclickhouse
  • 连接时指定 host、port（9000）、user、password，不走 HTTP
  • 注意：该库底层用 socket + 自定义二进制协议，比 HTTP 略快，但调试困难，错误信息不直观

---

smi2/phpclickhouse 写入大数据时内存爆掉？批量控制是硬要求

这个库默认把整个结果集读进内存，insert 大量数据时极易 OOM：

• 千万别用 ->write() 一次性传几百万行 CSV 字符串
• 正确做法是分块写入，每批 ≤ 5000 行：

  $client->write('my_table', $chunk, ['format' => 'TSV']);

• 如果源数据来自文件，优先用 clickhouse-client --query="INSERT INTO ... FORMAT TSV" < data.tsv 命令行导入，速度更快、内存零压力
• 库里 ->select() 返回的是完整二维数组，查亿级表前务必加 LIMIT，否则 PHP 进程直接被系统 kill

ClickHouse 的“快”建立在列存 + 向量化执行上，但 PHP 层只是个瘦客户端，所有性能优化点都在 SQL 写法、分区裁剪、物化视图预计算这些地方，PHP 代码本身没多少可调空间。