Unity SDK 通过 Registry 分发及第三方依赖处理指南

第一部分：理解 Unity Package Manager (UPM) 与 Registry

UPM 基础概念
- UPM 是什么？
  - Unity用来管理Package的工具。来解决传统导入.unitypackage插件，版本不好管理，升级不方便的问题。
- UPM 靠什么维护Package的信息？
  - package.json 文件：包的核心元数据文件（名称、版本、依赖、Unity 版本兼容性等）。
- UPM 中管理的包的类型有哪些？
  - embedded (项目内), git (Git 仓库), registry (包仓库)
Registry 的基础概念
- 什么是 Registry？
  - 一个集中存储和管理 UPM 包的服务器。
- Registry 分类
  - 官方 Registry：Unity 官方包源（https://packages.unity.com）
  - 非官方Registry：
    - 比较欢迎的开源Registry：
      - OpenUPM，地址是：(https://package.openupm.com)
    - 私有Registry，比如GitLab、Nexus
- Unity 中配置 Registry
  - 在 Unity Editor 中添加私有 Registry 源 (Project Settings > Package Manager)。
  - 使用 Scopes：如何通过命名空间 (com.yourcompany) 来组织和过滤包。

第二部分：准备并打包你的 Unity SDK

创建项目结构

使用推荐的项目结构

bash 复制代码

<com.youcompany.sample>
-- package.json
-- README.md
-- CHANGELOG.md
-- LISTENS.md
-- Editor
-------- com.youcompany.sample.editor.amsdef
-------- 脚本文件
-- RUNTIME
--------- com.youcompany.sample.runtime.amsdef
--------- 脚本文件
--------------- PLUGINS
--------------------- Android
---------------------------- AAR
--------------------- iOS
---------------------------- Framework
--------------------- BridgeScripts
-- OtherAsset(可选)
-- TEST(可选)
-- Sample~(可选)
-- Document~(可选)
</com.youcompany.sample>

程序集定义文件 (asmdef) 的使用：优化编译、明确依赖关系。

编写 package.json
- 关键字段详解：
  - name: 遵循 com.[yourcompany].[packagename] 格式。
  - version: 语义化版本号 (major.minor.patch)。
  - displayName: 用户友好的名称。
  - description: 包的描述。
  - unity: 最低兼容的 Unity 版本 (如 2021.3)。
  - dependencies: 声明对其他 UPM 包的依赖（名称和版本）。
  - author: 作者信息。
  - keywords: 搜索关键词。
  - samples: (可选) 如何包含示例代码。

第三部分：本地测试包（重要）

在发布之前，现在本地测试，功能是否正常，并方便修改。
- 通过 file: 协议引用本地开发的包进行测试，指向package.json。就相当于pod中的path。这样就会在Unity Packages 文件加下，引入本地的SDK工程，并能实时修改
- 比如:file://sdk/com.sdk.sample/

第四部分：发布 SDK 到 Registry

搭建私有 Registry (简述)
- 可选方案：Verdaccio (轻量级)、Nexus Repository Manager (功能强大)、GitLab。
- 如果是GitLab用户，可以直接使用GitLab，下面以GitLab为例。
发布包到 Registry 到 GitLab
- 如果会有多个Package，比如同一个公司下的，com.company.account、com.company.pay，建议使用GitLab的Group发布，但是GitLab 15.7以上才支持。

bash 复制代码

#检查GitLab版本

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/version"

#token获取
#GitLab->Edit Profile->Access Tokens->Personal Access Token
#创建一个api、read_reposity、write_reposity权限的token

GitLab版本支持

bash 复制代码

# 配置 GitLab Token（首次需要）
npm config set -- '//gitlab.sample.com/api/v4/groups/<YOUR-Group-Name>/-/packages/npm/:_authToken' "<YOUR_GITLAB_TOKEN>"

# 发布 Beta 版本
npm publish

GitLab版本不支持
- 多个Package 发布到中央Project，类似Group

bash 复制代码

# 配置 GitLab Token（首次需要）
npm config set -- '//gitlab.sample.com/api/v4/projects/<YOUR-Project-ID>/-/packages/npm/:_authToken' "<YOUR_GITLAB_TOKEN>"

# 发布 Beta 版本

# package.json 里面设置了publish config，并指定了registry
npm publish

# package.json 里面没有设置publish config
npm publish --registry https://gitlab.sample.com/api/v4/projects/<YOUR-Project-ID>/packages/npm/

第四部分：处理第三方 SDK 依赖

识别依赖类型
- UPM 包依赖 ：依赖项本身也是通过 UPM 分发的包（如官方的 com.unity.textmeshpro）。
  - 在 package.json 的 dependencies 字段中直接声明（如 "com.unity.textmeshpro": "3.0.0"）
  - Unity会自动下载
- 非 UPM 第三方 SDK ：
  - 传统方式提供的 SDK（如 Facebook SDK 的 .unitypackage 或 .aar/.framework）强依赖 (必须包含)
    - 方案 1：引导用户安装 ：
      - 在你的包文档中明确说明需要哪些第三方 SDK。
      - 提供下载链接和手动安装步骤。
      - (高级) 尝试在 Editor 脚本中检查并提示用户安装（但无法自动化）。
    - 方案 2：直接打包 ：将第三方 SDK 的库文件（.dll, .a, .so, .bundle）、资源文件等放入你的 UPM 包的 Runtime 或平台特定文件夹（如 Runtime/Android）中。注意版权和分发许可！
  - Registry方式提供的SDK
    - 通过Unity Regitry 管理界面，先添加三方Registry，比如openupm
    - 在 package.json 的 dependencies 字段中直接声明（如 "com.google.edm4u": "1.2.179"）
    - Unity会自动下载
    - 再引入自己的SDK

第五部分：用户使用与最佳实践

用户如何安装你的 SDK
- 在 Unity Editor 的 Package Manager 窗口中，选择你的私有 Registry 源。
- 搜索你的包名 (com.yourcompany.yoursdk) 并点击安装。
- 或者，在 manifest.json 中直接添加依赖项。
提供示例
- 利用 Samples~ 文件夹提供开箱即用的示例场景和脚本。
测试、测试、再测试
- 在不同 Unity 版本中测试你的包。
- 测试在新项目和已有项目中安装。
- 测试依赖解析（尤其是第三方依赖）。
- 测试升级和降级过程。

参考：

https://blog.csdn.net/qq_37672438/article/details/155231599?sharetype=blogdetail&sharerId=155231599&sharerefer=PC&sharesource=qq_37672438&spm=1011.2480.3001.8118