Puerts Unity插件运行时库配置问题分析与解决方案

2025-06-07 20:42:46作者：瞿蔚英Wynne

问题背景

Puerts是一个将TypeScript/JavaScript引入Unity游戏开发的强大工具，它通过桥接技术让开发者能够在Unity中使用前端技术栈进行开发。在最新发布的2.0.4版本中，有用户反馈在Unity 2022.3.13环境下，当项目部署到Android平台时遇到了运行时库配置问题。

问题现象

具体表现为两个关键问题：

Android平台x86_64架构支持缺失：虽然项目中包含了x86_64架构的目录结构，但实际缺少对应的动态链接库文件(.so文件)，导致在x86_64架构的Android设备上运行时会出现库加载失败的情况。
Linux平台库文件配置冲突：libpuerts.so和libnode.so这两个关键库文件在Unity中的平台配置存在问题。它们的meta文件中平台设置勾选了"Any Platform"，这会导致在构建Android版本时产生平台冲突，影响最终打包结果。

技术分析

Unity插件平台配置机制

Unity的插件系统通过.meta文件来管理不同平台下的资源配置。每个原生插件(.so/.dll等)都对应一个.meta文件，其中包含详细的平台配置信息：

平台标识：明确指定插件适用的平台(如Android、Linux、Windows等)
CPU架构：针对移动平台，需要指定支持的CPU架构(ARMv7、ARM64、x86等)
加载设置：控制插件在不同平台下的加载行为

Puerts运行时库依赖

Puerts在Unity中的运行依赖于两个核心库：

libpuerts.so：Puerts的核心运行时库，负责TypeScript/JavaScript的解析和执行
libnode.so：Node.js的运行时环境，提供JavaScript引擎支持

这两个库需要针对不同平台进行正确配置，才能确保在各种环境下正常工作。

解决方案

针对上述问题，我们提供了以下解决方案：

1. 修复Android x86_64支持

确保在Plugins/Android/x86_64目录下包含以下文件：

libpuerts.so
libnode.so.93

同时需要正确配置这些文件的.meta信息，确保Unity打包时能够正确识别和处理这些库文件。

2. 修正Linux平台库配置

更新libpuerts.so和libnode.so的.meta文件配置，移除"Any Platform"的全局勾选，改为针对特定平台的精确配置。以下是推荐的配置要点：

明确平台划分：为每个平台(Editor、Linux64、OSXUniversal等)设置独立的配置区块
架构指定：对于Editor环境，明确指定x86_64架构
Android排除：确保Linux配置不会影响Android平台的打包

配置示例

以下是经过优化的.meta文件配置示例(以libpuerts.so.meta为例)：

fileFormatVersion: 2
guid: [唯一标识符]
PluginImporter:
  serializedVersion: 2
  isPreloaded: 1
  platformData:
  - first: { : Any }
    second: { enabled: 0 }
  - first: { Android: Android }
    second: { enabled: 0 }
  - first: { Editor: Editor }
    second: 
      enabled: 1
      settings: { CPU: x86_64, OS: Linux }
  - first: { Standalone: Linux64 }
    second: { enabled: 1 }
  - first: { Standalone: OSXUniversal }
    second: { enabled: 1 }
  - first: { Standalone: Win }
    second: { enabled: 1 }
  - first: { Standalone: Win64 }
    second: { enabled: 1 }