Linux下PHP Libsodium最新库安装失败：部分函数无法调用

首先，你的推测方向完全正确——sodium_crypto_pwhash这个函数的可用性确实和PHP版本/扩展版本直接相关，这也是你遇到「部分函数正常、部分函数提示不存在」的核心原因。

为什么会出现这个问题？ #

sodium_crypto_pwhash是在PHP 7.2版本才被正式纳入libsodium扩展的；同时，如果你的libsodium扩展版本低于1.0.13，哪怕PHP版本达标，也会缺少这个函数。而你能正常使用sodium_crypto_generichash和sodium_crypto_secretbox，是因为这两个函数在更早的扩展版本中就已经存在了。

先做版本排查 #

先搞清楚你的PHP和libsodium扩展的具体版本，执行以下命令：

# 查看PHP版本
php -v
# 查看libsodium扩展详细信息
php -i | grep -A 10 sodium

或者写个简单的PHP脚本放在Web目录运行：

<?php
echo "PHP版本: " . PHP_VERSION . "<br>";
echo "libsodium扩展版本: " . (extension_loaded('sodium') ? phpversion('sodium') : '未加载') . "<br>";
echo "系统libsodium库版本: " . (defined('SODIUM_LIBRARY_VERSION') ? SODIUM_LIBRARY_VERSION : '无法获取') . "<br>";
echo "sodium_crypto_pwhash是否存在: " . (function_exists('sodium_crypto_pwhash') ? '是' : '否') . "<br>";
?>

如果输出里PHP版本低于7.2，或者libsodium扩展版本低于1.0.13，那问题根源就找到了。

针对性解决方案 #

方案1：升级PHP到7.2及以上（最推荐） #

如果服务器环境允许，直接升级PHP是最彻底的解决办法（毕竟PHP 7.0、7.1早已停止维护）。不同Linux发行版的升级命令如下：

• Debian/Ubuntu系列：

sudo apt update
# 安装PHP 7.2及对应libsodium扩展（可替换为8.0/8.2等更高版本）
sudo apt install php7.2 php7.2-sodium
# 重启Web服务（以Apache为例）
sudo systemctl restart apache2
# 若使用PHP-FPM，需重启对应版本的FPM服务
sudo systemctl restart php7.2-fpm

• CentOS/RHEL系列：

# 先安装EPEL和Remi源（Remi源提供新版PHP）
sudo yum install epel-release
sudo yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
# 启用PHP 7.2的Remi仓库
sudo yum-config-manager --enable remi-php72
# 安装PHP和libsodium扩展
sudo yum install php php-sodium
# 重启服务
sudo systemctl restart httpd
sudo systemctl restart php-fpm

方案2：升级libsodium扩展到最新版 #

如果暂时无法升级PHP，可以尝试升级PECL上的libsodium扩展：

# 强制重新安装最新版扩展
sudo pecl install -f libsodium

安装完成后，检查你的php.ini文件（通常在/etc/php/7.x/cli/php.ini或/etc/php/7.x/apache2/php.ini）是否包含extension=sodium.so这一行，若没有则手动添加，最后重启Web服务和PHP-FPM。

方案3：手动编译升级系统libsodium库 #

如果PECL安装的扩展仍不可用，可能是系统自带的libsodium库版本过低，需要先升级系统库再重新编译扩展：

1. 安装编译依赖：

# Debian/Ubuntu
sudo apt install build-essential libtool autoconf
# CentOS/RHEL
sudo yum install gcc gcc-c++ make autoconf libtool

2. 下载并编译最新版libsodium库：

cd /tmp
wget https://download.libsodium.org/libsodium/releases/libsodium-1.0.18.tar.gz
tar xzf libsodium-1.0.18.tar.gz
cd libsodium-1.0.18
./configure --prefix=/usr/local
make && sudo make install

3. 重新安装PECL扩展：

sudo pecl install -f libsodium

4. 重启服务，再次测试函数可用性。

最后验证 #

写个简单的测试脚本确认问题是否解决：

<?php
if (function_exists('sodium_crypto_pwhash')) {
    // 简单测试函数功能
    $password = 'your_test_password';
    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
    $key = sodium_crypto_pwhash(
        32,
        $password,
        $salt,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    );
    echo "函数正常工作！生成的密钥长度: " . strlen($key);
    // 安全清理敏感数据
    sodium_memzero($password);
    sodium_memzero($key);
} else {
    echo "sodium_crypto_pwhash函数仍然不存在，请检查版本是否正确。";
}
?>

运行脚本后，如果能正常输出密钥长度，就说明问题已经解决了。

内容的提问来源于stack exchange，提问作者Geoff L