PHP中SQLite3的JSON1扩展启用方法及编译后报错排查

首先得明确：JSON1是SQLite 3.9.0及以上版本的内置扩展，PHP的sqlite3扩展是否自带这个功能，完全取决于编译PHP时绑定的SQLite版本和配置。下面分不同环境给你说具体操作：

Windows环境 #

• PHP 7.4及以上版本：官方预编译的PHP包已经默认把JSON1整合进php_sqlite3.dll了，你只需要打开php.ini，确保extension=sqlite3这一行没有被注释掉（去掉前面的;），重启PHP服务就搞定。
• PHP 7.0-7.3版本：官方包没带JSON1，你要么自己编译带JSON1的php_sqlite3.dll，要么找第三方靠谱的编译版本，替换掉PHP安装目录ext文件夹里的原文件，再在php.ini开启extension=sqlite3就行。

Linux环境 #

• 编译PHP时配置：如果是从头编译PHP，要确保绑定的SQLite版本≥3.9.0。编译参数可以用--enable-sqlite3（如果用PHP自带的SQLite，只要版本够就会自动包含JSON1），或者指定系统中已安装的高版本SQLite：--with-sqlite3=/usr/local/sqlite3（这里的路径换成你实际的SQLite安装路径）。
• 已安装的PHP验证：先检查当前SQLite版本，执行命令：

  php -r "echo SQLite3::version()['versionString'];"
  

  如果输出的版本≥3.9.0，那JSON1已经可用，不需要额外配置；如果版本不够，就得更新系统的SQLite库，然后重新编译PHP的sqlite3扩展。

验证是否启用成功 #

执行下面的PHP代码，能正常输出{"test":1}就说明JSON1已经生效：

<?php
$db = new SQLite3(':memory:');
var_dump($db->querySingle('SELECT json(\'{"test":1}\')'));
?>

你替换自己编译的dll后出现报错，大概率是编译过程中存在兼容性问题，我给你梳理几个排查方向：

• 先确认版本和架构完全匹配
  这是最常见的坑：你编译php_sqlite3.dll用的PHP源码版本，必须和你当前运行的PHP版本完全一致（比如都是PHP7.2.34，连小版本都不能差），不同版本的PHP扩展接口不兼容，替换后肯定加载失败。另外，架构也要对应——如果你的PHP是64位的，编译的dll也必须是64位；32位同理，不然会提示“不是有效的Win32应用程序”。

• 检查编译参数是否正确
  JSON1是SQLite的内置功能，只要你编译时用的SQLite版本≥3.9.0，并且没有手动禁用JSON1，就会自动包含。编译php_sqlite3.dll时，要确保：

  1. 使用对应PHP版本的开发包（php-devel）来编译；
  2. 链接的SQLite库是带JSON1的（如果是自己编译SQLite，要确保编译SQLite时没加-DSQLITE_DISABLE_JSON1这类参数）。

• 查看PHP错误日志找具体原因
  打开php.ini，找到error_log配置项，设置一个可写的日志路径，然后重启PHP服务，触发报错后去日志里看具体信息。比如日志里提示缺少某个依赖dll（比如sqlite3.dll核心文件），那你得把对应的依赖文件放到PHP根目录或者系统System32文件夹里；如果提示“无法加载扩展”，那基本就是版本或架构不兼容。

• 验证扩展是否成功加载
  打开命令行执行php -m，看看输出的扩展列表里有没有sqlite3：

  • 如果没有，说明扩展根本没加载成功，回到前面的版本/架构/依赖排查；
  • 如果有，但执行代码报错，那可能是编译时的SQLite版本和PHP预期的不一致，或者编译过程中某个环节出了问题，比如编译参数漏了关键配置。

• 试试官方预编译包（如果可行）
  如果你的PHP版本是7.4及以上，直接去PHP官网下载对应版本的php_sqlite3.dll替换就行，官方版本已经默认整合了JSON1，不用自己折腾编译，能省很多麻烦。

内容的提问来源于stack exchange，提问作者Nigel Alderton