一、制作你的第一个 Package

Unity Package 不做过多赘述，像 URP 本质上也是一个 Package，在 Unity 中可以通过菜单栏 → Window → Package manager 来管理你当前的所有 Package

本篇文章主要介绍：如何制作并发布属于你的 Package

1.1 Package 主要包含以下内容

你的 Package 所实现的功能/提供的工具本身，其中的内容包括但不限于：

• C# 脚本
• 程序集 Assembly
• 原生插件 Plugin
• 模型、贴图、材质、音频等其他资产

除此之外，还需要添加 package 信息文件

• 修改日志 CHANGELOG.md
• 说明文件 README.md
• 版权声明 LICENSE.md
• 文档 Document~ （文件夹名后加~可使工程忽略该文件夹，文档仍是 md）

以及每个包还必须包含一个 Package 清单：package.json 文件，用于声明包体信息，包括名称、版本、依赖和仓库地址等

1.2 Package 目录结构

对于单一 Package：官方手册推荐布局样式

<root>
  ├── package.json
  ├── README.md
  ├── CHANGELOG.md
  ├── LICENSE.md
  ├── Editor
  │   ├── Unity.[YourPackageName].Editor.asmdef
  │   └── EditorExample.cs
  ├── Runtime
  │   ├── Unity.[YourPackageName].asmdef
  │   └── RuntimeExample.cs
  ├── Tests
  │   ├── Editor
  │   │   ├── Unity.[YourPackageName].Editor.Tests.asmdef
  │   │   └── EditorExampleTest.cs
  │   └── Runtime
  │        ├── Unity.[YourPackageName].Tests.asmdef
  │        └── RuntimeExampleTest.cs
  └── Documentation~
       └── [YourPackageName].md

例如 URP Package 的第一层目录如下：

如果你有多个 Package，可以再添加一层，便于管理：

例如上，其中根文件夹用你的名字（作者名字），子文件夹为每个独立的 Package

1.2.1 各个目录里应该放置哪些内容

Editor 文件夹

• 包含一些只在编辑器中使用的功能，在这里放置的脚本将只在 Unity 编辑器环境中执行
• 需在 Editor 文件中添加对应的 asmdef 文件

Runtime 文件夹

• 包含在游戏运行时使用的功能，这里的脚本将在游戏运行时执行
• 在 Runtime 文件添加对应的 Unity.TestPackage.asmdef

Tests 文件夹或其他文件夹

• 包含你的测试场景、及其对应的材质、音效、场景等资产等。对于这部分内容，确保移除后不会影响你 package 本身的功能，实际大项目应用该 package 时，可以选择只要 Runtime 和 Editor 部分的内容

1.3 Package 信息清单文件和配置文件

1.3.1 Package 配置清单文件：package.json

每个 Package 都必须要有一个 package.json 文件，用于配置 Package 信息，在 Package 导入项目后，这些信息会在 Package Manager 窗口展示出来

必要信息

• name：包名，需满足如下命名规范：①包名起始必须为 com.<company-name>，例如 com.happyengine-clusterlight；②需低于 50 个字符，且仅能包含小写字母、数字、连字符-、下划线_和点.
• version：版本号，需遵守：主版本.次版本.补丁版本规则即 x.x.x

建议信息

• displayName：在编辑器中的展示名称
• description：简介，展示与 Package Manager 窗口中，支持 UTF-8 编码字符
• unity：支持当前 package 的最小 Unity 版本
• author：作者信息，可包含 name，email 和 url

其它可选信息：

• keywords：Package Manager 搜索 API 使用的关键字数组，这可以帮助用户找到相关的包，对于公司内的仓库而言，完全可以不填
• unityRelease：针对上面的 version，补充指明特定的 Unity 发行版本：例如 44f1
• dependencies：当前 package 依赖的其它包名及版本，key 为包名，value 为版本，可以有多个，不支持范围语法，例如 "com.happyengine-clusterlight": "1.0.0"
• documentationUrl：当前 package 对应的文档

一个例子：

{
    "name": "com.happyengine-clusterlight",
    "version": "1.0.0",
    "displayName": "Hyychen.ClusterLight",
    "description": "移动平台实时动态多点光源方案",
    "unity": "2020.3",
    "documentationUrl": "https://blog.csdn.net/Jaihk662/article/details/137153400",
    "dependencies": {},
    "keywords": [
      "Cluster",
      "MultipleLight"
    ],
    "author": {
      "name": "Jaihk662",
      "email": "1045376785@qq.com",
      "url": "https://blog.csdn.net/Jaihk662"
    }
}

1.3.2 License 版权文件

符合法律要求 - Unity 手册

1.3.3 ChangeLog 文件

用于记录当前 package 的每一次更新内容，可以理解为是 git commit log，可以通过类似于 git 工具自动导出，一个简单的例子如下：文件名称必须为 CHANGELOG.md，且同样需要放在 package 的根目录下

# Changelog
## [1.0.0] - 2024-02-29
- ClusterLight ViewSpace 初版完成
## [2.0.0] - 2024-03-04
- 添加了一个室内场景用于测试
- ClusterLight ViewSpace 实现
## [3.0.0] - 2024-03-05
- 修改测试场景的光照及材质表现
## [4.0.0] - 2024-03-11
- 支持 WorldSpace ClusterLight
## [5.0.0] - 2024-03-26
- 支持 CPU 计算 ClusterLight，以适配不支持 ComputeShader 的手机

建议还是要有一份，除非你没有做版本管理 or 只有当前一个版本

1.3.4 Readme 文件

用于展示在你 package 主页的内容，和 Git README.md 文件作用一致，可使用 markdown 编辑器编辑，文件名称必须为 README.md

一般可以只填写注意事项，如果不想专门写的话，里面存放你功能对应的文档链接即可

二、程序集定义和包

包中的 .cs 脚本文件必须与程序集定义文件 .asmdef 关联（在同一目录下），.asmdef 等同于 .Net 生态的 C# 工程，得益于此功能，开发者可以在一个文件夹中自定义程序集。定义明晰的依赖关系，也可以确保脚本更改后，只会重新生成必需的程序集以减少编译时间

2.1 创建你当前 package，Runtime 及 Editor 下的 asmdef 文件

程序集定义 (Assembly Definition) 属性 - Unity 手册

可通过右键 → Assets > Create > Assembly Definition 菜单来创建当前默认的 asmdef 文件

对于 Editor 目录：需要将特定于 Editor 的代码存储在根 Editor 程序集定义文件中：

Editor/[YourCompany].[YourPackageName].Editor.asmdef

asmdef 文件会把其所在文件夹下的脚本打入同一个程序集中，如果一个文件夹及子文件夹中有多个 asmdef 文件，每个脚本被添加到离这个脚本最短路径的 asmdef 中去。如果你搞不清楚一个脚本究竟被包含在了哪个 asmdef 中，只需要选中这个脚本，在 Inspector 面板中就会清楚的看到

同理对于 Runtime 目录，也需要将特定于运行时的代码存储在根运行时程序集定义文件中：

Runtime/[YourCompany].[YourPackageName].Runtime.asmdef

如果你的其它目录中（例如 Test 目录）也包含 CS 脚本，则也需要配置相关的测试程序集：例如

Runtime/[YourCompany].[YourPackageName].Test.asmdef

2.2 asmdef 文件配置信息

程序集定义文件格式 - Unity 手册

只新增 asmdef 是不够的，还需要进行设置，首先是依赖关系

若一程序集内代码有对其他程序集的代码的引用，则必须在.asmdef的 Inspector 中Assembly Definition References选项下添加对该程序集文件的引用，例如你当前的 Editor 极大概率需要依赖其 Runtime asmdef：

如果想要将已经预编译好的程序集（dll）关联到 assembly definition file 中，需要勾选上面的 Override References 后再添加对应的 dll

同时对于不同平台的代码，根据代码作用在.asmdef文件的Platforms选项下选定程序集运行平台，例如对于 Editor 的 asmdef 而言，其必然只会在 Editor 下生效，Unity 仅在包含的平台上编译或引用此程序集

如果你的 Runtime 逻辑不区分平台，则保持默认设置 Any Platform

Package 中部分代码想要选择性的参与编译，可以通过在 Assembly Definition File 中 的 Version Define 自定义宏，并选择宏开启的条件，条件一般为：

1. 在特定的程序集存在的情况下启用宏（图中 Resource 展开选择即可）
2. 在特定版本的程序集存在的情况下启用宏，如对版本不做限制，输入0.0.0 或留空即可

当然还要注意

1. 直接在界面中选择 package 可能只能选择当前已经存在的 package，这明显是不科学的，因为启用该宏的 package 可能不存在，此时需要你用文本打开 asmdef 文件直接编辑
2. 如果确信程序集存在且版本正确，但是宏未启用，请为插件重新生成 vs 项目，具体方式为 Edit → Preferences → External Tools → Regenerate project files

---

其他一些不是特别重要的配置信息大部分情况下都可以保持默认，例如 Define Constraints，有特殊需求可以直接参考前面 2.1 提供的官方文档的链接

三、发布 or 获取你的 package

3.1 使用本地的 package

注意，用于开发 package 的工程，和你实际安装 package 的工程不能是同一个！也就是 Asset 下和 Packages 下不能出现相同的两份代码，不然会出现重复加载问题。如果想要测试下载你自己开发的 package，可以启用一个空项目

如果你前面对 package 的设置没有问题，就可以测试添加自己的 package 了

1. 开启一个空项目，或者打开一个正常研发的项目（例如 ROMeta）
2. 通过 Window → PackageManager 尝试添加你的 package，或者直接修改 Packages 根目录下的 manifset.json 文件

最后进入游戏，检查 package 对应功能是否正确，此时你也可以通过 UPM 找到自己的 package

3.1.1 *你项目里所有的 Package，它们都在哪里

Unity 的 Package Manager - Unity 手册

可以确定的是，这些 package 不会在你的 Asset 文件里，那么它们究竟在哪呢？

你的 package 会默认存储在 library/packagecache/ 目录下，项目是直接读取这个目录的，此时如果你要修改 package 里面的内容（例如修改 URP 源码），就不行，因为 library/packagecache/ 目录更像是一个存储 cache 的地方，如果对应的 package 有更新，那么你修改的内容也会丢失，同时你的项目 git 也不会管理 library 目录

因此，如果你要修改他人的 package 源码，需要将对应的 package 目录挪到和 Assets 同级的 Packages 目录下（其它目录也可，不过需要修改 manifest.json），而非保留在原位置 (library/packagecache/)

当然你也可以放置到其它的自定义位置，只要确保不在 library、Assets 等已有规则的目录中即可，不过此时就需要修改 manifest.json 文件，重新指定其 package 位置，一个格式参考如下

"com.unity.render-pipelines.core": "file:../HappyEnginePackages/com.unity.render-pipelines.core@10.10.1",
"com.unity.render-pipelines.universal": "file:../HappyEnginePackages/com.unity.render-pipelines.universal@10.10.1",
"com.unity.textmeshpro": "file:../HappyEnginePackages/com.unity.textmeshpro@3.0.6",
"com.happyengine-clusterlight": "file:../HappyEnginePackages/com.happyengine-clusterlight@5.0.0",

其对应的位置如下

当然，UPM 还有一个叫做 global cache 的地方，位置为 %LOCALAPPDATA%\Unity\cache，这个地方也会存放 Unity 的 packages 作为 unity 的所有版本所有项目的 cache，在 unity 启动的时候，它会本地启动一个 http server 并会往这个 local server 发请求，然后这个 local server 会从 manifest.json 中读取信息，从你配置的 registry 下载相关的 packages，如果发现 global cache 没有的，它会在那里放一份，如果发现有的，它就会直接从 global cache 里面拷贝一份到打开的项目

因此，如果你某个 package 一直报错，并且和你当前的 Unity 项目无关，可以尝试删除这个目录下的对应 package，并将 library/packagecache/ 也删除后重试，定能解决问题

3.2 发布的 package 需满足的规范

依照具体项目而定

3.3 使用 UPM 发布你的 package

依照具体项目而定