宝塔 Linux 安装 OpenCC 与 PHP 8.5 扩展完整教程:编译、配置、测试及备份回滚

适用环境:Linux 宝塔或 aaPanel,已经安装 PHP 8.5,使用 root 登录终端。按顺序执行,出现报错先停止。命令中的 cd 已写好,不需要自己判断进入哪个目录。

没有安装过 OpenCC:从第一部分开始。已经安装过 OpenCC:从第二部分开始。两种情况最后都执行第三部分。现有 PHP 7.4、OpenCC 库和字典无需卸载。

使用固定版本 OpenCC 1.1.9 和已验证的扩展源码,不代表最新版本。代码框可直接复制;右上角复制按钮由网站主题或代码插件提供。

先安装编译工具

Ubuntu、Debian 执行:

apt-get update
apt-get install -y build-essential autoconf automake libtool cmake git pkg-config python3 ca-certificates

Rocky、AlmaLinux、CentOS Stream 执行下面这一组。两组只选适合自己系统的一组。

dnf install -y gcc gcc-c++ make autoconf automake libtool cmake git pkgconf-pkg-config python3 ca-certificates

第一部分:全新安装 OpenCC

已经有 OpenCC 的服务器不要执行这一部分,直接看第二部分。

1、下载固定版本源码:

cd /usr/local
git clone --branch ver.1.1.9 --depth 1 --recurse-submodules https://github.com/BYVoid/OpenCC.git OpenCC
cd /usr/local/OpenCC

2、编译安装。下载成功后才执行;不要在 git clone 报错或提示目录已存在后直接继续。

cmake -S /usr/local/OpenCC -B /usr/local/OpenCC/build-php85 \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DLIB_INSTALL_DIR=/usr/local/lib \
  -DSHARE_INSTALL_PREFIX=/usr/local/share \
  -DBUILD_SHARED_LIBS=ON \
  -DBUILD_DOCUMENTATION=OFF \
  -DBUILD_PYTHON=OFF \
  -DENABLE_GTEST=OFF \
  -DENABLE_BENCHMARK=OFF \
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
  -DCMAKE_POLICY_DEFAULT_CMP0148=OLD
cmake --build /usr/local/OpenCC/build-php85 --parallel 2
cmake --install /usr/local/OpenCC/build-php85

三个命令依次执行:前一个成功再执行下一个。安装输出中应该包含 /usr/local/lib 和 /usr/local/share/opencc。

3、让系统找到库,并保存后面需要的路径:

printf '/usr/local/lib\n' > /etc/ld.so.conf.d/opencc-php85.conf
ldconfig
printf 'OPENCC_PREFIX=/usr/local\nOPENCC_LIBSUBDIR=lib\nOPENCC_DATA_DIR=/usr/local/share/opencc\n' > /root/opencc85-paths.env
chmod 600 /root/opencc85-paths.env
/usr/local/bin/opencc --version

看到 OpenCC 版本后,直接执行第三部分,不用执行第二部分。

第二部分:已经安装过 OpenCC

只找出现有路径,不重新安装底层库和字典。下面整段执行,最后会打印三个实际路径。路径文件只是让后面的命令自动使用它们,不需要你手动替换。

(
  set -eu
  command -v pkg-config >/dev/null
  pkg-config --variable=pcfiledir opencc
  OPENCC_PREFIX="$(pkg-config --variable=prefix opencc)"
  OPENCC_LIBDIR="$(pkg-config --variable=libdir opencc)"
  test -n "$OPENCC_PREFIX"
  case "$OPENCC_LIBDIR" in
    "$OPENCC_PREFIX"/*) OPENCC_LIBSUBDIR="${OPENCC_LIBDIR#"$OPENCC_PREFIX"/}" ;;
    *) echo 'Library path is outside prefix; stop and check the existing installation.' >&2; exit 1 ;;
  esac
  OPENCC_DATA_DIR="$(pkg-config --variable=pkgdatadir opencc)"
  if [ -z "$OPENCC_DATA_DIR" ] || [ ! -r "$OPENCC_DATA_DIR/s2twp.json" ]; then
    declare -A FOUND=()
    for d in "$OPENCC_PREFIX/share/opencc" /usr/share/opencc /usr/local/share/opencc; do
      if [ -r "$d/s2twp.json" ] && [ -r "$d/tw2s.json" ]; then
        REAL="$(readlink -f "$d")"
        FOUND["$REAL"]=1
      fi
    done
    if [ "${#FOUND[@]}" -ne 1 ]; then
      echo 'No unique dictionary directory. Stop and check the existing installation.' >&2
      exit 1
    fi
    for d in "${!FOUND[@]}"; do OPENCC_DATA_DIR="$d"; done
  fi
  test -r "$OPENCC_PREFIX/include/opencc/opencc.h"
  test -e "$OPENCC_LIBDIR/libopencc.so"
  for mode in s2t t2s s2tw tw2s s2hk hk2s s2twp tw2sp; do
    test -r "$OPENCC_DATA_DIR/$mode.json"
  done
  umask 077
  if [ -e /root/opencc85-paths.env ]; then
    cp -a /root/opencc85-paths.env "/root/opencc85-paths.env.before-$(date +%Y%m%d-%H%M%S)"
  fi
  {
    printf 'OPENCC_PREFIX=%q\n' "$OPENCC_PREFIX"
    printf 'OPENCC_LIBSUBDIR=%q\n' "$OPENCC_LIBSUBDIR"
    printf 'OPENCC_DATA_DIR=%q\n' "$OPENCC_DATA_DIR"
  } > /root/opencc85-paths.env
  cat /root/opencc85-paths.env
)

例如当前这台服务器会显示:OPENCC_PREFIX=/usr、OPENCC_LIBSUBDIR=lib、OPENCC_DATA_DIR=/usr/share/opencc。其他服务器的结果可以不同,不要强行改成这个。然后继续第三部分。

第三部分:给 PHP 8.5 安装扩展(两种情况通用)

1、下载扩展源码:

cd /usr/local
git clone https://github.com/nauxliu/opencc4php.git opencc4php-85
cd /usr/local/opencc4php-85
git checkout --detach 9000997ba8b1a4f4935ae8d9ec390f1b4a6b3dc1

如果已经编译过:例如你当前这台服务器,已经存在 /usr/local/opencc4php-85/modules/opencc.so,直接从下面第 3 步测试开始,不用重新下载和编译。其他情况下若目录已存在且编译状态不明确,先检查,不能直接跳过。

2、使用 PHP 8.5 的工具编译。configure 成功结束后再执行 make。

cd /usr/local/opencc4php-85
. /root/opencc85-paths.env
/www/server/php/85/bin/phpize
./configure --with-php-config=/www/server/php/85/bin/php-config --with-opencc="$OPENCC_PREFIX" --with-libdir="$OPENCC_LIBSUBDIR"
make -j2

make 成功时通常会显示 Build complete.。扩展文件在 /usr/local/opencc4php-85/modules/opencc.so。

3、先测试,不改 PHP 配置。整段执行:

. /root/opencc85-paths.env
/www/server/php/85/bin/php -n -d extension=/usr/local/opencc4php-85/modules/opencc.so -r '
$dir = $argv[1];
if (!chdir($dir)) { throw new RuntimeException("Dictionary directory unavailable"); }
$h = opencc_open($dir . "/s2twp.json");
if ($h === false) { throw new RuntimeException("Cannot open dictionary"); }
try {
    $result = opencc_convert("我的鼠标哪儿去了?", $h);
    if ($result === false) { throw new RuntimeException("Conversion failed"); }
    echo $result, PHP_EOL;
} finally { opencc_close($h); }
' -- "$OPENCC_DATA_DIR"

正确输出:我的滑鼠哪兒去了?。如果报错,先不要执行后面的安装。这里不需要创建 verify.php,也不需要处理 100 次循环。

4、备份配置和已有扩展:

BACKUP="/root/opencc85-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -m 700 "$BACKUP"
cp -a /www/server/php/85/etc/php.ini "$BACKUP/php.ini"
EXT_DIR="$(/www/server/php/85/bin/php-config --extension-dir)"
if [ -f "$EXT_DIR/opencc.so" ]; then cp -a "$EXT_DIR/opencc.so" "$BACKUP/opencc.so"; fi
printf '%s\n' "$EXT_DIR" > "$BACKUP/extension-dir.txt"
printf '%s\n' "$BACKUP" > /root/opencc85-last-backup.txt
echo "备份目录:$BACKUP"

看到备份目录后,记下它。备份只读取 PHP 8.5,不修改 PHP 7.4。

5、安装编译好的扩展:

cd /usr/local/opencc4php-85
make install

会输出类似:Installing shared extensions: /www/server/php/85/lib/php/extensions/……/。这是实际扩展安装目录,不需要手动猜目录名。

6、打开宝塔 → 软件商店 → PHP 8.5 → 配置文件。先搜索 opencc,如果已有有效的 extension 配置就不要重复添加;如果没有,在配置末尾添加:

[opencc]
extension = opencc.so

保存后,在 PHP 8.5 的服务页面点击“重载配置”。不用重载 PHP 7.4,也不用立即切换正式网站版本。

7、确认扩展已经启用:

/www/server/php/85/bin/php --ri opencc

应该显示 OpenCC 的扩展信息。如果提示 Extension opencc not present,检查是否改了 PHP 8.5 的配置文件,而不是其他版本;不要重复追加很多行。

第四部分:测试网站能否转换

先保存实际字典目录,网页测试会自动读取,不用改代码里的目录:

. /root/opencc85-paths.env
printf '%s\n' "$OPENCC_DATA_DIR" > /usr/local/opencc4php-85/opencc-data-dir.txt
chmod 644 /usr/local/opencc4php-85/opencc-data-dir.txt
cat /usr/local/opencc4php-85/opencc-data-dir.txt

在使用 PHP 8.5 的测试网站根目录中新建 opencc-test.php,内容如下:

<?php
header('Content-Type: text/plain; charset=utf-8');
if (!extension_loaded('opencc')) {
    throw new RuntimeException('OpenCC not loaded');
}
$directory = trim(file_get_contents('/usr/local/opencc4php-85/opencc-data-dir.txt'));
if ($directory === '' || !chdir($directory)) {
    throw new RuntimeException('Dictionary directory unavailable');
}
$handle = opencc_open($directory . '/s2twp.json');
if ($handle === false) {
    throw new RuntimeException('Cannot open s2twp.json');
}
try {
    $result = opencc_convert('我的鼠标哪儿去了?', $handle);
    if ($result === false) { throw new RuntimeException('Conversion failed'); }
    echo PHP_VERSION, PHP_EOL, $result, PHP_EOL;
} finally {
    opencc_close($handle);
}

浏览器访问 https://你的测试域名/opencc-test.php。正常会显示 PHP 8.5 的版本,以及 我的滑鼠哪兒去了?。测试完成后删除这个测试文件。

如果网页提示 open_basedir 限制,在该测试网站已有的允许目录中,增加刚才 cat 显示的字典目录和 /usr/local/opencc4php-85,保留原有目录,不要关闭全局限制或改成 777。

以后换服务器,路径怎么办?

全新安装会把字典放在 /usr/local/share/opencc;已有 OpenCC 的服务器会使用它原来的位置。前面已经保存路径,后面的命令自动读取。底层库和字典可以供不同 PHP 版本共用,PHP 扩展需要按 PHP 版本分别编译。

现有业务程序如果自己写了固定字典路径,仍要检查其写法;本教程不会自动改业务程序。上面的测试 PHP 使用保存的实际路径。

安装后有问题,怎样恢复?

下面恢复本教程备份的 PHP 8.5 配置和扩展。应在本次安装发现问题后及时使用;若之后又修改了 php.ini,先保留那些修改,再决定是否整份恢复。

(
set -eu
BACKUP="$(cat /root/opencc85-last-backup.txt)"
EXT_DIR="$(cat "$BACKUP/extension-dir.txt")"
test "$EXT_DIR" = "$(/www/server/php/85/bin/php-config --extension-dir)"
cp -a "$BACKUP/php.ini" /www/server/php/85/etc/php.ini
if [ -f "$BACKUP/opencc.so" ]; then
    cp -a "$BACKUP/opencc.so" "$EXT_DIR/opencc.so"
else
    rm -f "$EXT_DIR/opencc.so"
fi
/www/server/php/85/sbin/php-fpm -t -y /www/server/php/85/etc/php-fpm.conf
/etc/init.d/php-fpm-85 reload
)

验证范围:所用源码版本、路径规则和现有服务器的转换已核对;全新环境没有在每种 Linux 发行版逐一实装。参考:OpenCC 源码、PHP 扩展源码。

发布者:彬彬笔记,转载请注明出处:https://www.binbinbiji.com/jianzhanjiaoliu/3808.html

赞 (0)
彬彬笔记彬彬笔记
上一篇 2026年9月5日 17:27
Google Chrome自动更新的解决办法,Google Chrome 便携版下载
下一篇 2025年8月21日 17:53

相关推荐

发表回复

登录后才能评论
蜀ICP备14017386号-13