PHP Fatal Error: Call to undefined function bcmul() 解決方案（缺少 bcmath 擴展）

在遷移服務器、升級 PHP 版本或部署支付/加密相關代碼時，常遇到 Fatal error: Call to undefined function bcmul()。根因是 PHP 未安裝或未啟用 BCMath 任意精度數學擴展。本文提供針對不同 Linux 發行版、PHP 版本的安裝修復步驟，並介紹 BCMath 基本用法。

錯誤現象

PHP Fatal error: Call to undefined function bcmul() in /var/www/html/php_rsa.php on line 42

原因分析

• bcmul()、bcadd()、bcdiv() 等函數屬於 BCMath 擴展，非 PHP 核心內置，默認未編譯/安裝。
• 常見於：支付簽名驗證（RSA/ECC）、加密解密庫、金融金額計算、科學計算代碼。

解決方案：安裝 php-bcmath / php53-bcmath / php7.x-bcmath

CentOS / RHEL / Rocky / AlmaLinux (yum/dnf)

# 1. 檢查可用包
yum search bcmath | grep php

# 2. 安裝對應 PHP 版本的 bcmath
# PHP 5.4/5.5/5.6 (remi 源)
yum install php-bcmath

# PHP 7.0
yum install php70-php-bcmath
# PHP 7.1
yum install php71-php-bcmath
# PHP 7.2
yum install php72-php-bcmath
# PHP 7.3
yum install php73-php-bcmath
# PHP 7.4
yum install php74-php-bcmath
# PHP 8.0
yum install php80-php-bcmath
# PHP 8.1
yum install php81-php-bcmath

# 3. 重啟 PHP-FPM / Apache
systemctl restart php-fpm
# 或
systemctl restart httpd

Ubuntu / Debian (apt)

# PHP 7.4
apt update && apt install php7.4-bcmath

# PHP 8.0
apt install php8.0-bcmath

# PHP 8.1
apt install php8.1-bcmath

# PHP 8.2
apt install php8.2-bcmath

# 重啟
systemctl restart php7.4-fpm  # 或對應版本
systemctl restart nginx       # 若用 Nginx

常見坑：依賴衝突（php53-common vs php-common）

若出現 Error: php53-common conflicts with php-common，說明系統同時存在 PHP 5.3 和 5.4+ 的包，需安裝對應版本：

yum install php53-bcmath  # 針對 PHP 5.3
# 或
yum update && yum install php53-bcmath

驗證安裝

php -m | grep bcmath
# 輸出 bcmath 表示成功

php -r "var_dump(function_exists('bcmul'));"  # bool(true)

BCMath 基本用法速查

<?php
// 任意精度乘法
echo bcmul('1.34747474747', '35', 3); // 47.161 (保留 3 位小數)
echo bcmul('2', '4');                  // 8

// 任意精度加法
echo bcadd('123456789123456789', '987654321987654321'); // 1111111111111111110

// 任意精度除法
echo bcdiv('10', '3', 10); // 3.3333333333

// 設置全局默認小數位
bcscale(4);
echo bcmul('1.2', '3.4'); // 4.0800 (自動 4 位小數)

// 比較
echo bccomp('1.000', '1.0', 3); // 0 (相等)
echo bccomp('1.001', '1.0', 3); // 1 (大於)

// 平方根（需 PHP 7.3+）
echo bcsqrt('2', 10); // 1.4142135623
?>

php.ini 相關配置

[bcmath]
; 所有 bcmath 函數的默認小數位數
; https://php.net/manual/en/bc.configuration.php#ini.bcmath.scale
bcmath.scale = 0

建議：在代碼中顯式傳遞 $scale 參數，避免依賴全局配置導致跨環境行為不一致。

替代方案：GMP 擴展

若服務器已安裝 GMP（php-gmp），可用 gmp_mul()、gmp_add() 等函數，性能更優、功能更全（支持大整數質數測試、隨機數等），但 API 風格不同（資源類型 vs 字符串）。BCMath 字符串風格更簡單，適合金融/支付場景。

總結檢查清單

1. 確認 PHP 版本：php -v
2. 安裝對應版本 bcmath 包（yum/apt/brew/源碼編譯 --enable-bcmath）
3. 重啟 PHP-FPM / Web 服務器
4. php -m | grep bcmath 驗證
5. 重現原報錯場景確認修復

安裝 BCMath 擴展是解決 bcmul() undefined 的標準答案。養成「部署前檢查擴展依賴、代碼中顯式聲明精度」的習慣，能避免 99% 的精度計算部署故障。