sodium 扩展是现代 PHP 应用处理密码、JWT 等加密功能的必需底层支柱，需通过 php -m 和 php -i 验证是否启用，并区分 CLI 与 Web 的 php.ini 路径；Linux/macOS 宜用包管理器安装并启用，Docker 中用 docker-php-ext-enable sodium，Windows 下需取消 php.ini 中 extension=libsodium 注释且确保 OpenSSL 已启用。
不是所有 PHP 环境默认启用 sodium 扩展，但现代 Laravel、Symfony 或依赖 paragonie/sodium_compat 的包（如 league/oauth2-server）会直接要求它——报错“The requested PHP extension sodium is missing from your system.”时，别急着降级依赖，先确认并启用扩展。
怎么确认 sodium 确实没启用
运行命令验证真实状态，避免误判：
-
php -m | grep sodium—— 无输出即未加载 -
php -i | grep "sodium support"—— 输出enabled才算生效 - 注意 CLI 和 Web 使用的 php.ini 可能不同：
php --ini查看实际加载路径，别只改了 Apache 的配置却在终端跑 install
Linux/macOS 下启用 sodium 的实操要点
多数现代发行版的 PHP 包已内置 sodium，但需手动启用：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- Debian/Ubuntu：
sudo apt install php-sodium（PHP 8.1+ 默认已含，但扩展仍需单独启用） - macOS + Homebrew：
brew install php@8.2后，检查/opt/homebrew/etc/php/8.2/conf.d/ext-sodium.ini是否存在且内容为extension=sodium - 若用 Docker，Dockerfile 中加一行：
RUN docker-php-ext-enable sodium（不是docker-php-ext-install，后者已过时） - 重启 PHP CLI 进程：关掉所有终端再新开，或执行
hash -r清 shell 缓存
Windows 下常见坑与绕过方式
Windows 用户容易卡在 DLL 加载失败或版本不匹配：
- PHP 7.2+ 自带 sodium，但
php.ini里要取消注释：extension=libsodium（旧版写extension=php_sodium.dll，新版统一为libsodium） - XAMPP/WAMP 用户常忽略：控制面板里“PHP 扩展”开关只是 UI，最终仍要检查
php.ini文件是否真被修改 - 如果启用了但
php -i仍显示 disabled，可能是 OpenSSL 未启用（sodium 依赖 OpenSSL 初始化），先按 openssl 故障排查流程走一遍 - 临时绕过（仅调试）：
composer install --ignore-platform-reqs，但装完大概率在password_hash()或 JWT 签名时崩溃，不解决根本问题
sodium 不是可选加密玩具，它是现代 PHP 应用处理密码、JWT、加密通信的底层支柱；启用它本身不耗资源，但漏掉会导致整个 auth 流程静默失败——别等上线后才发现登录 500，本地 php -m 多敲一次比 debug 两小时划算。
