Newtonsoft.Json-for-Unity 安装与使用指南

Newtonsoft.Json-for-Unity 是一个专门为 Unity 游戏引擎定制的 Newtonsoft.Json 版本，解决了在 IL2CPP 构建和其他 AOT（Ahead-of-Time）目标下的兼容性问题。

项目概述

Newtonsoft.Json（又称 Json.NET）是 .NET 生态系统中最流行的高性能 JSON 框架。这个 fork 版本包含了针对独立平台、便携式平台（UWP、WP8）以及所有 IL2CPP 构建（iOS、WebGL、Android、Windows、Mac OS X 等）AOT 目标的定制构建。

重要说明：官方替代方案

自 2022 年 2 月起，Unity 已经发布了他们官方的 Newtonsoft.Json 包：com.unity.nuget.newtonsoft-json@3.0。这个官方包实际上是基于这个 fork 的再 fork，包含了所有 IL2CPP 和托管代码剥离的 bug 修复。

推荐使用官方包，因为它由 Unity 员工维护更新，并且在较新版本的 Unity 中通常已经包含，无需额外安装。

项目特性

• 提供 Newtonsoft.Json v10.0.3、v11.0.2、v12.0.3 和 v13.0.1 的替代版本
• 完整的 IL2CPP 构建支持
• 通过 Unity Package Manager 交付，便于更新和版本切换
• 预编译为 DLL，构建速度更快
• 包含 Newtonsoft.Json.Utility.AotHelper 工具类，用于解决常见的 AOT 问题

安装方法

安装官方 UPM 包（推荐）

1. 打开项目的 Packages/manifest.json 文件
2. 添加或替换依赖项：

{
  "dependencies": {
    "com.unity.nuget.newtonsoft-json": "3.0.1"
  }
}

传统安装方法（已弃用）

虽然官方推荐使用 Unity 的官方包，但了解传统的安装方法仍然有帮助：

通过 OpenUPM 安装

openupm add jillejr.newtonsoft.json-for-unity

通过 Git URL 安装

在 Unity 的 Package Manager 中，选择 "Add package from git URL" 并输入：

https://github.com/jilleJr/Newtonsoft.Json-for-Unity.git#upm

通过 UnityPackage 安装

下载对应的 .unitypackage 文件并通过 Unity 的包导入功能安装。

项目结构

项目的核心文件位于 Src/Newtonsoft.Json-for-Unity/ 目录下：

• Plugins/ - 包含预编译的 DLL 文件
  • Newtonsoft.Json AOT/ - AOT 目标版本
  • Newtonsoft.Json Editor/ - 编辑器版本
• package.json - UPM 包配置文件
• LICENSE.md - 许可证信息
• README.md - 项目说明文档

配置文件说明

package.json

这是 Unity Package Manager 的核心配置文件，定义了包的基本信息：

{
  "name": "jillejr.newtonsoft.json-for-unity",
  "displayName": "Json.NET 13.0.1 for Unity",
  "version": "13.0.102",
  "unity": "2018.1",
  "description": "Json.NET is a popular high-performance JSON framework for .NET",
  "license": "MIT"
}

manifest.json

在 Unity 项目中，最重要的配置文件是 Packages/manifest.json，它定义了项目依赖的所有外部包。

使用示例

在代码中使用 Newtonsoft.Json-for-Unity：

using Newtonsoft.Json;
using UnityEngine;

public class JsonExample : MonoBehaviour
{
    [System.Serializable]
    public class PlayerData
    {
        public string playerName;
        public int score;
        public Vector3 position;
    }

    void Start()
    {
        // 序列化对象到 JSON
        PlayerData player = new PlayerData
        {
            playerName = "Player1",
            score = 100,
            position = new Vector3(1, 2, 3)
        };
        
        string json = JsonConvert.SerializeObject(player);
        Debug.Log(json);

        // 从 JSON 反序列化对象
        PlayerData deserializedPlayer = JsonConvert.DeserializeObject<PlayerData>(json);
        Debug.Log(deserializedPlayer.playerName);
    }
}

解决 AOT 问题

对于 IL2CPP 构建，可能需要使用 AotHelper 来解决序列化问题：

// 在应用程序启动时调用
Newtonsoft.Json.Utility.AotHelper.EnsureType();

或者创建 link.xml 文件来防止必要的类型被剥离：

<linker>
  <assembly fullname="Newtonsoft.Json">
    <type fullname="Newtonsoft.Json.*" preserve="all"/>
  </assembly>
</linker>

常见问题

GUID 冲突

如果遇到 GUID 冲突错误，这是因为官方包和这个包同时存在。解决方案是移除这个包，完全使用官方包。

版本兼容性

确保选择的 Newtonsoft.Json 版本与你的 Unity 版本和目标平台兼容。

贡献与支持

虽然这个项目现在已经基本被官方包替代，但如果你遇到问题：

• 查看官方文档：Newtonsoft.Json 文档
• 在 Unity 论坛寻求帮助
• 查看 Stack Overflow 上关于 json.net 的问题

许可证

这个项目遵循 MIT 许可证，详细信息请查看 LICENSE.md 文件。

---

注意：强烈建议使用 Unity 官方的 com.unity.nuget.newtonsoft-json 包，因为它提供了相同的功能并由 Unity 官方维护。