编程 ICU4C 链接报错与数据加载排查:符号后缀 _79、SONAME 跳变与 libicudt

2026-11-19 00:03:53

ICU4C 链接报错与数据加载排查:版本后缀、SONAME 与 libicudt

结论先给:三类「像是没装 ICU」的报错成因不同。undefined reference 多是头文件与 .so 不同源(renaming 状态或版本后缀不一致),或漏链 icu-i18n;cannot open shared object file 是 SONAME 随大版本跳变导致加载期找不到;U_MISSING_RESOURCE_ERROR 是数据没被加载,而不是数据文件不存在。

项目信息

  • 仓库:https://github.com/unicode-org/icu (icu4c/ 子目录)
  • 文档:https://unicode-org.github.io/icu/
  • 官网:https://icu.unicode.org/

ICU4C 是 International Components for Unicode 的 C/C++ 侧,与 Java 侧的 ICU4J 是姊妹项目,需要区分时写 ICU4C。至少需要 data(libicudt)与 common(libicuuc)两个库。

现象

三种报错看起来都像「没装 ICU」:

  1. undefined reference to icu_79::UnicodeString::... 或 undefined reference to ucnv_open_79
  2. libicui18n.so.79: cannot open shared object file
  3. 程序跑起来了,取 locale 数据返回 U_MISSING_RESOURCE_ERROR(UErrorCode = 2)

第一步:分清是符号名不对,还是库根本没找到

nm -D /usr/lib/x86_64-linux-gnu/libicuuc.so | grep ucnv_open
# 输出 ucnv_open_79,带版本后缀

readelf -d /usr/lib/.../libicui18n.so.79 | grep SONAME
# 输出 libicui18n.so.79
  • 自带的 icuinfo 会打印 ICU version、DataVersion、config(含 renaming 是否开启),比 icu-config --version 更直接。
  • uconv -V 输出形如 uconv v2.1 ICU 79.1。

命名空间与符号重命名(renaming)

  • ICU 61 起头文件不再默认把 ICU 类型放进全局作用域,要写 icu::UnicodeString 或 using icu::UnicodeString;。依赖旧的隐式 using 会报找不到符号,临时兼容可用 -DU_USING_ICU_NAMESPACE=1。
  • C++ 实际命名空间是带版本的 icu_79,icu 只是稳定别名。要写前向声明用 U_NAMESPACE_BEGIN / U_NAMESPACE_END。
  • C API 走的是 entry point 重命名:符号名追加 _79。如果发行版用 --disable-renaming 编译,符号就是 ucnv_open,命名空间也是 icu。头文件和 .so 必须同源同版本,混用系统里另一份 ICU 头文件就会报 undefined reference。

pkg-config 取代 icu-config

  • icu-config 自 ICU 63.1 起弃用(ICU-10464),可能被默认关闭;configure 有 --enable-icu-config / --disable-icu-config。
  • 推荐 pkg-config,包名:icu-uc(common+data)、icu-i18n(国际化)、icu-lx(ParagraphLayout)、icu-io(ustdio)。
c++ -o test test.cpp $(pkg-config --libs --cflags icu-uc icu-io)
  • .pc 文件装在 $(prefix)/lib/pkgconfig,自定前缀时要 export PKG_CONFIG_PATH=$(prefix)/lib/pkgconfig。
  • 常见坑:只链 icu-uc 却在用 icu::Collator / icu::DateFormat,这两个在 icu-i18n,报的就是 undefined reference。
  • 自己搭构建系统时,各库要分别定义 -DU_COMMON_IMPLEMENTATION / -DU_I18N_IMPLEMENTATION,单库合并加 -DU_COMBINED_IMPLEMENTATION,静态库加 -DU_STATIC_IMPLEMENTATION;不开这些会撞到符号可见性问题。
  • ICU4C 现在要求 C11 与 C++17,老工具链报一堆语法错时先看这条。
  • 源码构建顺序:
runConfigureICU Linux/gcc
gmake

非 GNU make 环境按配置结尾提示用 gmake。

数据加载:U_MISSING_RESOURCE_ERROR 不是文件缺失那么简单

  • 数据是独立一份的:libicudt。ICU 服务对象打开时(ucnv_open / ucol_open / C++ 构造函数)都会给 UErrorCode,必须逐个查,不能只看最后一次。
  • u_init()(uclean.h)返回失败,通常意味着数据文件找不到;它只加载一到两个文件,通过也不代表所有数据齐。
  • 数据打包四种形态:static / library(数据内嵌进 libicudt.so)/ files(散装 .res)/ shared。
  • 用 .dat 包(或 files 模式自定路径)时,必须在任何其它 ICU API 之前调用 u_setDataDirectory() 或 udata_setCommonData(),否则全部资源失败。
  • 数据包换字节序或字符集用 icupkg 工具处理。
  • uconv 在 source/extra/,官方明确不保证支持,但做码页转换排查很好用:uconv -l 列可用转换器,uconv -x Any-Hex 看实际码点。

升级时的互斥点

SONAME 随大版本跳变(libicui18n.so.78 → .79),没有稳定 ABI。PHP 的 intl、Node、PostgreSQL 的 ICU 依赖,只要有一环还链着旧 SONAME,就会在加载期报 cannot open shared object file 或 undefined symbol。做法是装新版本后立刻用 ldd 检查所有依赖 ICU 的二进制,而不是只看 ldconfig -p 里有几份。

与站内 #8612 的切面差异

#8612 讲 ICU4J 的 SPI 与 java.text.Collator 的兜底边界;这篇只切 ICU4C 的构建、链接与数据加载层。

复制全文 生成海报 ICU4C Unicode C++ 编译链接 国际化

推荐文章

程序员茄子在线接单