Puerts项目在Linux CI环境下libpuerts.so加载问题解析

问题背景

在Unity项目中使用Puerts进行TypeScript脚本开发时，开发者在Linux CI环境中遇到了libpuerts.so动态链接库加载失败的问题。错误表现为系统无法找到并加载libpuerts.so库文件，导致Puerts功能无法正常初始化。

错误现象分析

从错误日志中可以看到，系统尝试了多种路径和文件名变体来加载libpuerts.so，包括：

• /opt/unity/Editor/Data/MonoBleedingEdge/lib/puerts
• /opt/unity/Editor/Data/MonoBleedingEdge/lib/libpuerts.so
• /opt/unity/Editor/Data/MonoBleedingEdge/lib/libpuerts

最终系统抛出DllNotFoundException异常，提示开发者参考FAQ解决此问题。

根本原因探究

经过深入分析，这个问题可能由以下几个因素导致：

1. 库文件路径问题：Unity在Linux环境下搜索动态链接库的路径可能与预期不符，导致无法正确定位到libpuerts.so文件。

2. 平台配置错误：虽然开发者确认了libpuerts.so的meta配置正确设置为Linux x64平台，但在实际部署中可能存在配置冲突。

3. 依赖库缺失：尽管ldd检查显示所有依赖库都存在，但在CI环境中可能存在运行时环境差异导致依赖解析失败。

4. 命名冲突：项目中可能存在多个平台版本的libpuerts.so文件，Unity在加载时可能选择了错误的版本。

解决方案

1. 清理冗余库文件

开发者发现删除Plugins/Android/libs/x86_64/libpuerts.so文件后问题得到解决，即使该文件的导入设置已经配置为Android平台。这表明Unity在加载库文件时可能存在命名冲突问题。

建议：为不同平台的库文件使用唯一命名，例如：

• libpuerts_linux.so
• libpuerts_android.so
• libpuerts_win.so

2. 确保依赖库可用

在CI环境中，虽然安装了libc++等依赖库，但运行时仍可能遇到"libc++.so.1: cannot open shared object file"错误。这通常是由于：

• 库文件路径不在LD_LIBRARY_PATH环境变量中
• 安装的库版本不兼容
• 权限问题导致无法访问库文件

解决方案：

# 确保安装正确的库版本
sudo apt-get install -y libc++1 libc++abi1 libunwind8

# 检查库文件路径
sudo find / -name "libc++.so.1"

3. 强制加载诊断

在CI环境中，可以通过在启动时强制加载库文件来获取更详细的错误信息：

[DllImport("libpuerts")]
private static extern void ForceLoad();

这可以帮助诊断加载失败的具体原因，而不是让Unity静默失败。

最佳实践建议

1. 平台隔离：为每个目标平台创建独立的插件目录结构，避免文件命名冲突。

2. 依赖验证：在CI脚本中添加依赖库验证步骤，确保所有必需库已正确安装并可访问。

3. 日志增强：在Puerts初始化代码中添加更详细的日志输出，帮助诊断加载问题。

4. 环境检查：在CI环境中添加系统环境检查脚本，验证Unity版本、库路径等关键配置。

总结

Puerts在Linux CI环境中的库加载问题通常与文件路径、平台配置和依赖关系有关。通过规范命名、清理冗余文件、验证依赖关系以及增强诊断日志，可以有效解决这类问题。对于持续集成环境，建议建立完善的预检流程，确保构建环境的完整性和一致性，避免因环境差异导致的运行时问题。