【Unity3D框架】Unity Package Manager自定义包管理实践

一、概述

        在公司开发的前两个项目，虽然搭建了基础的框架，有一些目录划分，但是当项目复杂度增长到一定程度，以及后续新开了一些新的项目之后，对于基础框架的管理就遇到了一些挑战，主要体现在以下几个方面：

        1、多项目之间拷贝了类似的基础框架，但是在开发过程中各项目之间各自对内容进行修改，难以共享修改的结果。比如，对于如第三方sdk升级、对框架的bug修复等，在不同项目之间各升级一遍，该踩的坑要再各踩一遍等，实际上效率很低。

        2、新项目无法直接引入纯净的基础框架，需要整个复制其他项目的框架，以此为基础删掉逻辑。

        3、权限管理难，框架级的代码并不希望所有的组员都去更改。

        4、版本管理难，只能依靠git去做零碎的历史记录管理。

        5、没有对框架模块进行正经的模块化管理，命名规范、接口设计等方面在多人协作过程中容易逐渐演变地随意起来，难以管理。

        实际上，从Unity2017开始，Unity3D引擎本身就开始转向使用Unity Package Manager（UPM）管理Unity自身的功能模块，到后续Unity 2019乃至之后的版本，Unity Package Manager已经发展成为一个完善的包管理系统，Unity内置的功能，以及Asset Store的资源都可以通过Package Manager进行管理。

        为了解决上述遇到的这些问题，可以用UPM的方式管理我们的自定义包。使用思路如下：

        1、建立一个专用框架开发工程，使用git管理，只对希望有开发框架的权限的人员开放权限。

        2、在框架工程对各个基础模块解耦并独立出来，设计好多个Package包，导出.tgz包。

        3、搭建npm服务器，托管导出的.tgz包。

        4、在各客户端项目里配好服务器地址，各取所需引入对应的包。

二、UPM

        Unity Package Manager(UPM) 是Unity官方维护的一个包管理器。

        官方对应的说明如下:Unity - Manual: Unity's Package Manager (unity3d.com)https://docs.unity3d.com/2021.3/Documentation/Manual/Packages.html        Unity - Manual: Scoped registries (unity3d.com)https://docs.unity3d.com/2021.3/Documentation/Manual/upm-scoped.html#security        下面大致介绍一下一些重要的工具和概念。

2.1、Editor窗口

        Unity的Package Manager窗口可以通过Windows-Package Manager打开，界面如下(Unity 2021.3版)：

        其中主要的菜单项有：

        1、分类：如图中的Packages: In Project选项，下来项还包括Unity Registry（Unity官方包）、My Registry（我的自定义包）、My Assets（我的账号中拥有的Asset Store的资源）、Build-in（内置包）等

        2、设置：如图中的齿轮，设置中主要是打开Pre-released的非正式包、自定义Scropd Registry（即添加自定义的托管地址）等

        3、添加：加号按钮下拉项中有多种安装Pack的方式，包括从git URL，本地磁盘、压缩包、名字等方式

2.2、包目录结构

        在工程里，UPM管理的包的目录有两个：

        1、自定义的Package存放位置为与Assets目录同级Packages目录。

        2、下载的Package则存在于Library/PackageCache目录下（该目录下的文件无法被改动，改动后Unity刷新时会被覆盖掉）。

        此处在Packages目录创建了一个名为Demo Pack1的包（新版的专业版Unity有提供创建菜单，如果没有的版本，自行在目录里按规范建立文件也可以识别），此时Packages目录如下

        

        打开com.demo.pack1，目录结构大体如下：

        UPM的管理方式应该是基于Node.js的包管理系统，因此目录结构与Node.js非常相似。

       放有自定义包的工程，或者引用了该包的工程后，在Project窗口可以看到文件:

       以下对图中涉及到的文件和目录做简短说明：

        a、manifest.json和package-lock.json

        这两个文件是由Unity引擎进行管理的文件。

        manifest.json记录的是本工程引用了哪些包，以及对应的版本。在Package Manager的Editor窗口增删、升级等操作后的结果会记录在该文件。因此如果我们也可以按格式自己修改这个文件。

      package-lock.json则是unity自动解析和下载完成所有的包之后记录的详情。这个文件我们无需关心。

        b、包目录

        · package.json（必须）该文件是记录这个包的信息的文件。新建的这个自定义包的内容如下：

{
    "name": "com.demo.pack1",
    "displayName": "Demo Pack1",
    "version": "0.0.1",
    "unity": "2021.3",
    "description":"My first Demo Package",
    "dependencies": {
    }
  }

        其中，

        name是这个包的包名（一般按风格化命名，以英文句号.隔开）；

        displayName则是展示的名称；

        version是包的版本号；

        unity开发这个包时使用的Unity版本（可以理解为最低支持的unity版本吧）；

        description为描述；

        dependdencies为依赖；依赖格式为 "包名":"版本号"。如果填写了依赖的话，unity会自动下载对应的包。

        对应的displayName等字段的内容会在Editor窗口的详情页面对应展示。

        · Runtime目录（可选）：运行时代码存放的位置，一般用来存放对应运行时的C#代码和资源。

        · Editor目录（可选）：Editor代码存放的位置，一般用来存放编辑器代码和资源。

        · Plugins目录（可选）：原生层文件存放位置，如安卓或iOS的库等。

        · Documentation目录（可选）：点击Package Manager的Editor窗口展示的document按钮会跳转到这个目录

        · Samples~目录（可选）：如果有Demo演示的话可以放这个目录

        · CHANGELOG.md（可选）：发布日志，点击Package Manager的Editor窗口展示的changelog按钮会跳转并选中这个文件

三、托管

        如上文所述，添加自定义包的方式有多种，包括git URL、本地磁盘、压缩包等。此处由于使用的是打tgz包并使用npm服务器托管，因此只展示tgz包相关。

3.1、打包

        Unity提供了将Package导出为.tgz包的接口，我们可以通过自定义Editor工具去开发打包工具（后续新版Unity Pro版本可能提供一件导出包的功能，则无需自己开发）：

// Client.Pack
public static PackageManager.Requests.PackRequest Pack(string packageFolder, string targetFolder);

        此处引用一个找到的Github仓库自定义工具的例子：
LightBuzz/Unity-Package-Export: Export an existing Unity Package as a tarball (.tgz) file. (github.com)https://github.com/LightBuzz/Unity-Package-Export        

        导出.tgz包如下：

        

3.2、npm服务器

        托管服务器可以直接使用任意开源免费包含权限管理功能的npm服务器即可，此处推荐Sonatype Nexus服务器。

        对应服务器搭建方式已有很多大佬演示过，在此不再赘述，推荐一篇博客：
Sonatype Nexus安装-CSDN博客https://blog.csdn.net/qq_33697094/article/details/119346596        搭建完成之后能看到一个hosted的npm服务器

        使用服务器后台，可以简单的将tgz包上传，同时也可以在后台进行删除等操作。

3.3、客户端引入

        在客户端引入该包的方式也很简单。在上述Unity Package Manager界面中提到Scoped Registry界面填好服务器地址等信息，Unity即可识别到该服务器。

        实际上，在上述界面填写的结果，等同于，上述提到的manifest.json中增加字段：

,
  "scopedRegistries": [
    {
      "name": "Demo",
      "url": "http://example.com/unity-npm",
      "scopes": [
        "demo"
      ]
    }

        识别好服务器之后，即可通过名字在Unity Package Manager界面添加。或者直接在manifest.json中添加对应的项，比如自定义的包

        “com.demo.pack1”:"0.0.1"

        在权限分配正确，服务器搭建正确的情况下，以上步骤Unity即可自动识别并下载对应的包了。

四、一些技巧

        上文描述了使用UPM管理包、搭建托管服务器等内容。下面总结一些这一两年使用这个包管理方式时的一些小技巧。

        1、dll和命名空间管理

       在上述的目录结构中，我们可以看到Runtime和Editor是独立放置的。此外，包也有包名和展示名等字段。因此，非常适合用来做规范化的C#命名空间管理。

        比如按 公司/工作室名称.框架模块名称.细分目录名称去管理 命名空间。然后在对应的细分目录创建Assembly Definition，管理好Assembly的引用关系和平台等。

        这样做的好处主要是减少编译时间和规范化管理Pack。

        

                        

        Unity缓存的编译后的Assembly存放位置在Library/ScriptAssemblies目录下。如果有单独发布dll的需求或者对dll进行混淆的话，其实也可以用这种方式简单得到dll文件。

        

        2、代码中包路径问题

        在实践过程中，我们遇到最大的问题是，读取包内资源的路径与Assets下不同。这个问题尤其存在于如果我们有接入第三方sdk并进行简单封装的需求的时候尤为明显。

        如果都是自己的文件，那么还可以通过Path.GetFullPath("Packages/XXX")等方式去拼正确的路径，如果第三方sdk文件写了路径就比较麻烦。

        因此，此处推荐一种解决方案是，造一个专用的包，用ScriptableObject去标识需要再Assets目录里去读取的文件以及对应本来应该在Assets目录下的位置，然后使用Unity的Editor的生命周期函数，比如编译完或者导入完之后，遍历工程里的这些配置，自动把文件拷贝到Assets中。

        3、link.xml

        Packages中的link.xml文件等无法生效，因此只能通过Editor脚本自定义，或者上述第2点的工具拷贝的工程目录中。此外可能还有一些其它的格式，如lua代码，也不支持放在这些目录里，因此都可以用这种方式处理。

        4、meta

        由于发布压缩包的方式的meta文件是无法被外部的Editor修改的，如果使用了第三方dll(不是指上边提到的自己的Assembly Definition）等，如果meta文件变动了guid，会导致外部实例化资源引用丢失，所以尽量不要动已有包内dll等文件的meta。

        5、修改和合并

        在概述中提到了一点，我们并不希望所有人都会去改动到框架包。采用了tgz的方式托管的话，引用包在Cache目录下是无法被修改的。但是实际运作过程中，往往可能需要为框架做一些小的改动、bug修复或者调试。

        此时如果希望工程内可以修改的话，可以在PackageCache中找到对应的包目录，整个剪切到Packages目录下，此时这个远程包相当于转化成为了本地包。

        当我们对这个本地包修改、调试完成之后，再找框架工程的管理人员交付自己的改动，由专员合并完代码之后，发布新的版本包。项目工程此时只需要升级版本并且删除本地包，即可以完成迭代。

        6、版本管理

        由于自定义包是带版本的，推荐维护ChangeLog文件，以方便各项目知道版本更新了什么内容。不同项目之间按需安排时间升级测试版本包即可。

        7、更细致的权限管理

        由于我们使用的npm服务器也有版本权限管理，所以从公司代码安全的角度上讲，完全有可能实现项目工程git权限管理以外的核心框架包的另一层权限管理。