PHP安装YAML扩展：pecl安装libyaml方法

本文详细解析了PHP YAML扩展安装中极易踩坑的核心难点：必须先手动编译安装满足版本要求（≥0.2.5）的libyaml底层库，再安装PHP封装层扩展，否则无论Linux下pecl install还是Windows下启用dll都会因依赖缺失而失败；文章不仅揭露了系统包管理器（如apt）提供的libyaml版本过旧、pecl自动检测不可靠、多PHP环境路径混乱等常见陷阱，还给出了跨平台可落地的解决方案——从源码编译libyaml、手动编译php-yaml、正确部署yaml.dll位置及php.ini配置要点，直击开发者在实际部署中反复报错“libyaml not found”或“undefined reference to yaml_*”的根源，堪称一份避坑指南级的实战教程。

PHP 的 yaml 扩展不能只靠 pecl install yaml 一步到位——它依赖系统级的 libyaml 库，漏掉这层，编译会直接失败，报错类似 configure: error: libyaml not found 或 undefined reference to yaml_*。

Linux 下必须先装 libyaml，再装 php-yaml 扩展

PECL 的 yaml 是 PHP 封装层，底层调用的是 C 实现的 libyaml。系统没装这个库，./configure 阶段就会卡住。

• 不要用 apt install libyaml-dev 后就以为万事大吉——Debian/Ubuntu 的包版本太老（比如 Ubuntu 22.04 自带的是 libyaml-0.2.2），而 PHP YAML 扩展 2.2+ 要求 libyaml ≥ 0.2.5
• 推荐从源码编译安装：

  git clone https://github.com/yaml/libyaml
  cd libyaml
  ./bootstrap
  ./configure --prefix=/usr/local
  make && sudo make install

• 确保 pkg-config --modversion yaml 能输出 ≥ 0.2.5 的版本；如果不行，检查 /usr/local/lib/pkgconfig/ 是否在 PKG_CONFIG_PATH 中

pecl install yaml 失败时，手动编译更可控

很多环境下 pecl install yaml 会跳过 libyaml 检查或用错路径，尤其当系统有多个 PHP 版本或自定义安装路径时。

• 先确认 php-config 路径：which php-config 或 find /usr -name php-config 2>/dev/null
• 下载对应 PHP 版本的扩展源码（例如 PHP 8.2）：wget https://pecl.php.net/get/yaml-2.2.2.tgz
• 解压后执行：

  phpize
  ./configure --with-php-config=/usr/bin/php-config
  make && sudo make install

• 注意：如果 make install 输出的 .so 路径不在 extension_dir 里，得手动复制到正确目录（php -i | grep extension_dir 查看）

Windows XAMPP 环境下别漏掉 yaml.dll

Windows 不需要编译 libyaml，但容易忽略一个关键 DLL：除了 php_yaml.dll，XAMPP 还要求同名的 yaml.dll（C 运行时依赖）放在系统能加载到的位置。

• 从 PECL 下载的 ZIP 包里，有两个文件：php_yaml.dll（PHP 扩展）和 yaml.dll（libyaml 的 Windows 动态库）
• php_yaml.dll 放进 php\ext\ 目录（如 C:\xampp\php\ext\）
• yaml.dll 必须放进 C:\xampp\ 根目录（不是 php/ 子目录），否则 Apache 启动时报 PHP Startup: Unable to load dynamic library 'php_yaml.dll'
• php.ini 中写 extension=yaml（不带 .dll），不是 extension=php_yaml.dll

最容易被忽略的点是：libyaml 和 PHP YAML 扩展的版本兼容性。比如 libyaml 0.2.5 + yaml 2.2.2 可以，但 libyaml 0.1.7 + yaml 2.2.x 几乎必挂——别图省事复用旧系统包，宁可自己编译一份干净的 libyaml。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PHP安装YAML扩展：pecl安装libyaml方法》文章吧，也可关注golang学习网公众号了解相关技术文章。