A NuGet Package Manager for Unity
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 1 年前 | ||
| 4 个月前 | ||
| 2 年前 | ||
| 4 个月前 | ||
| 7 个月前 | ||
| 1 年前 | ||
| 10 年前 | ||
| 2 年前 | ||
| 1 年前 | ||
| 1 年前 | ||
| 1 年前 | ||
| 8 年前 | ||
| 1 年前 | ||
| 1 年前 |
NuGetForUnity 是什么？
NuGetForUnity 是一个专为 Unity 编辑器内部运行而从头构建的 NuGet 客户端。NuGet 是一个包管理系统，它能够轻松创建在服务器上分发并由用户使用的包。NuGet 支持 语义版本控制，同时也能够处理对其他包的依赖。
您可以在以下网站了解更多关于 NuGet 的信息：nuget.org
NuGetForUnity 提供了一个可视化编辑器窗口，用于查看服务器上的可用包、已安装包以及可用包更新。同时，还提供了一个可视化界面，以便在 Unity 中创建和编辑 .nuspec 文件，从而定义和发布您自己的 NuGet 包。
如何安装 NuGetForUnity？
通过 OpenUPM 安装
该包可在 openupm 注册表中获取。因此，您可以通过 openupm-cli 安装，或者使用作用域注册表手动安装，具体请查阅 openupm 上的文档。openupm add com.github-glitchenzo.nugetforunity
通过包管理器以 GIT 依赖项方式安装
Unity 2019.3 或更新版本
- 打开包管理器窗口（窗口 | 包管理器）
- 点击窗口左上角的
+按钮，并选择 "从 GIT URL 添加包..." - 输入以下 URL 并点击
添加按钮
https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity
注意： 若要安装特定版本，可以通过在版本前添加
#v{版本号}来指定版本，例如#v2.0.0。更多内容请参阅 Unity UPM 文档。
Unity 2019.2 或更早版本
-
关闭 Unity 编辑器
-
使用任意文本编辑器打开 Packages/manifest.json 文件
-
在
"dependencies": {后面插入以下行，并保存文件。"com.glitchenzo.nugetforunity": "https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity", -
在 Unity 编辑器中重新打开 Unity 项目
通过 .unitypackage 文件安装
将提供的 Unity 包安装到您的 Unity 项目中。位置在 这里。
下载 *.unitypackage 文件。在文件资源管理器中右键单击该文件，并选择 "在 Unity 中打开"。
如何使用 NuGetForUnity？
要启动，请选择 NuGet → 管理NuGet包
几秒钟后（查询服务器上的包可能需要一些时间），您应该会看到这样的窗口：
在线 选项卡显示 NuGet 服务器上可用的包。
启用 显示预发布版本 以列出包的预发布版本（alpha、beta、发布候选版等）。 禁用 显示预发布版本 仅显示稳定版本。
在 搜索 框中输入搜索词以筛选显示内容。
按下 刷新 按钮以使用最新的查询设置刷新窗口。（在将新包推送到服务器后，无需关闭并重新打开窗口即可查看新包非常有用。）
包名、发布者、下载次数和描述都会显示。
展开 详情 后，点击 查看许可 以在网页浏览器中打开许可。
点击 安装 以安装按钮旁边下拉列表中指定的包版本。 注意：如果已安装包，当前安装的版本将显示在右上角。 如果 安装 按钮被禁用，表示包已经被 Unity 导入。
您还可以选择多个包进行安装，并一次性安装它们。
除了手动选择，您还可以复制需要安装的 packageIds 列表，每行或逗号分隔，然后简单地点击右上方的 "从剪贴板选择所有" 按钮将它们全部添加到选择中。 注意，如果包已经被安装或在 Unity 中可用，则不会在选中列表中显示。
已安装 选项卡显示当前 Unity 项目中已安装的包。
列表中的 已安装包 部分显示直接作为项目依赖项安装的包。
隐式安装的包 部分显示作为传递依赖项安装的包。
点击 卸载 按钮卸载包。 在卸载 显式 安装的包时，所有不是其他包或项目本身的依赖项的依赖项也将被卸载。
如果对 隐式 安装的包点击 添加为显式，它将移动到列表的第一部分，并且在上述场景中 不会 被自动卸载。
更新 选项卡显示当前已安装的包，并提供更新到可用更高版本或降级到更低版本的选项。
如果未勾选 显示降级，所有可用版本高于当前安装版本的包将会显示，并且在 更新 按钮旁边会有一个下拉列表，列出可用的更新版本。
只有当未勾选 显示降级 时，全部更新 按钮才会显示，并且它将更新下拉列表中当前选择的版本的所有包。
类似地，如果勾选了 显示降级，所有可用版本低于当前安装版本的包将会显示，并且在 降级 按钮旁边会有一个下拉列表，列出可用的降级版本。
默认情况下，下拉列表中选择的版本是 最高的更新 或 最高的降级 版本，具体取决于 显示降级 复选框。
点击 更新（或 降级）按钮卸载当前包并安装新包。
在全新检出后恢复包
当您克隆或全新检出使用 NuGetForUnity 的 Unity 项目时，首次启动可能会遇到编译错误。这是因为 Unity 试图在 NuGetForUnity 有机会恢复 packages.config 文件中定义的所需 NuGet 包之前编译您的 C# 脚本。因此，任何引用 NuGet 包的代码都将无法编译，Unity 可能会提示您出现编译错误弹窗。
这是由于 Unity 加载编辑器插件和编译脚本的方式造成的已知限制。有两种主要方法避免或解决此问题：
选项 1：使用 CLI 恢复包（推荐用于 CI/CD）
在首次在 Unity 中打开项目之前，使用 NuGetForUnity CLI 工具恢复所有 NuGet 包。请参阅：通过命令行恢复 NuGet 包。
这将下载并安装 packages.config 中指定的所有所需包，在 Unity 尝试编译您的脚本之前。
选项 2：首次启动时忽略编译错误（推荐给开发者）
如果您打开项目并看到由于缺少 NuGet 包导致的编译错误：
- 当 Unity 在启动时显示编译错误弹窗时，选择 忽略（不是安全模式）。
- Unity 将继续其正常启动，而 NuGetForUnity 将在后台自动恢复缺少的包。
- 恢复完成后，Unity 将重新编译您的脚本，错误应该会自动解决。
或者，您可以通过 Unity 菜单手动触发包恢复：NuGet → 恢复包。
NuGetForUnity 如何工作？
NuGetForUnity 在 Unity 项目中加载 NuGet.config 文件（如果尚不存在，将自动创建），以确定它应该从哪个服务器下载包并上传包。默认情况下，这个服务器设置为 nuget.org 包源。
默认 NuGet.config 文件：
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<packageSources>
<clear />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</packageSources>
<activePackageSource>
<add key="All" value="(Aggregate source)" />
</activePackageSource>
<config>
<add key="repositoryPath" value="./Packages" />
</config>
</configuration>
您可以将此设置为任何其他 NuGet 服务器（例如 NuGet.Server 或 ProGet - 请参见下文）。如果您编辑了 NuGet.config 文件，NuGet → 恢复包 菜单选项将非常有用。关于 NuGet.config 文件的更多信息，请访问此处：https://docs.nuget.org/consume/nuget-config-settings
目录结构（配置文件和已安装包的存放位置）
NuGetForUnity 支持两种不同的目录结构，用于定义配置文件 NuGet.config、packages.config 和下载的 NuGet 包的 *.dll 文件的存储位置。这些位置可以在 NuGet For Unity 设置界面中更改。
自定义 Assets 目录内
NuGet.config 文件将被放置在 <Unity 项目位置>/Assets 目录下，而 packages.config 文件和已安装包的位置可以通过 NuGet.config 文件内的配置变量进行更改。NuGetForUnity 安装包的位置，即本地仓库路径，在 NuGet.config 文件中定义（repositoryPath）。默认情况下，这被设置为 Assets/Packages 文件夹。配置的路径可以是基于项目 Assets 文件夹的绝对路径或相对路径。注意：您可能希望您的 Packages 文件夹被版本控制软件忽略，以防止将 NuGet 包版本化到您的仓库中。
示例目录结构：
<Unity Project Location>
├── Assets
│ ├── NuGet.config
│ ├── packages.config
│ └── Packages
│ └── Serilog.2.12.0
│ ├── icon.png
│ └── lib
│ └── netstandard2.1
│ └── Serilog.dll
在 Packages 文件夹中
所有配置文件和安装的包均位于 <Unity 项目位置>/Packages/nuget-packages 内。这样一来，Assets 目录不会包含任何文件。在这种放置方式中，packages.config 文件的路径和已安装包的目录无法更改。
示例目录结构：
<Unity Project Location>
├── Packages
│ └── nuget-packages
│ ├── NuGet.config
│ ├── packages.config
│ └── InstalledPackages
│ └── Serilog.2.12.0
│ ├── icon.png
│ └── lib
│ └── netstandard2.1
│ └── Serilog.dll
packages.config 文件内容
当安装一个包时，项目中的 packages.config 文件会自动更新，包含特定的包信息以及同时安装的所有依赖项。这允许在任何时候从头开始恢复包。Restore 操作在每次打开项目或项目中的代码重新编译时自动运行。也可以通过选择 NuGet → 恢复包 菜单项手动运行。
注意：根据需要安装的包的大小和数量，Restore 操作可能需要 很长 时间，请耐心等待。如果Unity似乎没有启动或没有响应，请等待几分钟后再尝试终止进程。
详细日志记录
如果您想了解 NuGetForUnity 的处理过程或尝试调试问题，可以强制 NuGetForUnity 使用详细日志记录，以向 Unity 控制台输出更多信息。您可以在 NuGet For Unity 设置窗口中勾选 使用详细日志记录 复选框，或者在 NuGet.config 文件的 <config> 元素中添加 <add key="verbose" value="true" /> 行。您可以通过将值设置为 false 或完全删除该行来禁用详细日志记录。
缓存
从 NuGet 服务器下载的 .nupkg 文件会缓存在当前用户的应用程序数据文件夹中 %localappdata%\NuGet\Cache（Windows：C:\Users\[用户名]\AppData\Local\NuGet\Cache，Mac/Linux：~/.local/share/NuGet/Cache）。缓存位置可以通过设置 NuGetCachePath 环境变量来覆盖。已安装的包会通过缓存文件夹进行安装，而不是再次从服务器下载。
高级设置
使用自定义 NuGet 服务器
默认配置使用 nuget.org，但其他服务器上托管的包源也应该可以工作。有些需要特殊设置。这个设置可以通过配置用户界面 NuGet → 首选项 或者在 NuGet.config 中设置。以下是一些示例：
Azure Artifacts / GitHub Packages
它们需要设置 supportsPackageIdSearchFilter 为 false，例如：
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<packageSources>
<add key="github" value="https://nuget.pkg.github.com/NAMESPACE/index.json" supportsPackageIdSearchFilter="false" />
</packageSources>
<packageSourceCredentials>
<github>
<add key="userName" value="USERNAME" />
<add key="clearTextPassword" value="TOKEN" />
</github>
</packageSourceCredentials>
...
</configuration>
JFrog Artifactory
需要将 protocolVersion 设置为 3，其他必要的设置如 packageDownloadUrlTemplateOverwrite 应该能够自动检测/配置。
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<packageSources>
<add
key="Artifactory"
value="https://company.com/artifactory/api/nuget/v3/PROJECT"
protocolVersion="3"
packageDownloadUrlTemplateOverwrite="https://company.com/artifactory/api/nuget/v3/PROJECT/registration-semver2/Download/{0}/{1}"
updateSearchBatchSize="1"
/>
</packageSources>
<packageSourceCredentials>
<Artifactory>
<add key="userName" value="USERNAME" />
<add key="clearTextPassword" value="Password" />
</Artifactory>
</packageSourceCredentials>
</configuration>
在项目 NuGet.config 文件之外存储凭证
当使用需要 UserName 和 Password 的自定义 NuGet 服务器时，您很可能不会将这些信息存储在 Unity 项目中的 NuGet.config 文件中，因为它将被提交到源代码控制。因此，我们支持从系统级或用户特定的 nuget.config 文件中加载 packageSourceCredentials 部分。系统级或用户特定 nuget.config 文件的存储位置在 Microsoft 的 NuGet 配置文档中有说明（例如，在 Windows 上为 %AppData%\NuGet\NuGet.Config）。
禁用程序集自动引用
要禁用 NuGet 包的程序集自动引用，您可以在 packages.config 文件中将包的 autoReferenced 属性设置为 false。目前此设置在用户界面中不可用。
<?xml version="1.0" encoding="utf-8" ?>
<packages>
<package id="Serilog" version="2.12.0" autoReferenced="false" />
</packages>
当此设置值为 false 时，NuGet 包的程序集仅被那些在其 *.asmdef 文件中明确列出它们的 Unity 项目引用。
如何在 Unity 中创建自己的 NuGet 包？
首先，您需要创建一个 .nuspec 文件来定义您的包。在您的项目窗口中，右击想要放置 .nuspec 文件的位置，并选择 NuGet → 创建 Nuspec 文件。
选择新的 .nuspec 文件，您应该会看到类似这样的内容：
输入与您的包相关的适当信息（ID、版本、作者、描述等）。请确保包括您的包所需的任何依赖项。
按下 打包 按钮将您的包打包到一个 .nupkg 文件中，该文件保存在 C:\Users\[用户名]\AppData\Local\NuGet\Cache 文件夹内。
按下 推送 按钮将您的包上传到服务器。确保设置正确的 API 密钥，以获得推送到服务器的权限（如果您的服务器配置为使用 API 密钥）。
如何创建自己的 NuGet 服务器来托管 NuGet 包？
您可以使用 NuGet.Server、NuGet Gallery、ProGet 等来创建自己的 NuGet 服务器。
注意： NuGetForUnity 不使用 Microsoft 官方的 NuGet 客户端实现，因此目前不支持对所有第三方 NuGet 服务器的认证。如果您遇到认证问题，请创建一个问题，以便我们尝试实现。
或者，您可以使用“本地源”，这只是一个位于您硬盘或网络共享上的文件夹。本地 NuGet 源可以有两种不同的结构：
- 平面结构：<本地源路径>/<包 ID>.<包版本>.nupkg
- 层次结构：<本地源路径>/<包 ID>/<包版本>/<包 ID>.<包版本>.nupkg
确保在 NuGet.config 文件中设置正确的 URL/路径，然后您应该就可以使用了！
更多信息请访问：http://docs.nuget.org/create/hosting-your-own-nuget-feeds
通过命令行恢复 NuGet 包
对于那些使用自动化构建解决方案（如 持续集成）的项目，NuGetForUnity 提供了直接从命令行恢复 NuGet 包的功能，而无需启动 Unity。这是通过使用单独的 NuGetForUnity.Cli NuGet 包实现的，其中包含一个 .Net 工具。
安装
- 作为系统范围的全局工具使用：
dotnet tool install --global NuGetForUnity.Cli。 - 作为项目/文件夹范围内的本地工具使用：可以创建一个工具清单（本地工具安装上下文），使用：
dotnet new tool-manifest。然后安装 NuGetForUnity.Cli，使用：dotnet tool install NuGetForUnity.Cli。然后将工具清单.config/dotnet-tools.json添加到您的版本控制系统中。
更多信息请查看 .Net 工具文档。
使用
恢复单个 Unity 项目的 Nuget 包：dotnet nugetforunity restore <项目路径>。如果作为全局工具安装，可以不用 dotnet 前缀调用：nugetforunity restore <项目路径>。
插件支持
NugetForUnity 支持插件。如果您打开 Unity 首选项中的 NugetForUnity 部分，它将列出您在项目中安装的插件，您可以从那里启用它们。
插件是任何包含 NugetForUnityPlugin 在其名称中，并且其中有一个类实现了 INugetPlugin 接口的 dll。它们可以放在项目中的任何位置（在 Assets 目录内）。
如果您有兴趣实现一个插件，请阅读 插件开发文档。
安装 NuGet 包时的常见问题
在 .Net 生态系统中，Unity 相对较为特殊，因为它没有使用 Microsoft 标准的 .Net 运行时，而是使用了一个 Mono 运行时的分支。Unity甚至在某些平台上使用 IL2CPP 将所有 C# 代码编译为 C++ 代码。因此 Unity 也使用了一个不同的构建系统。这可能会导致某些依赖于标准 .Net 构建系统的 NuGet 包出现问题。NuGetForUnity 尝试处理大多数需要的更改，以便在 Unity 中使用 NuGet 包，但它无法解决所有问题。本节包含一些常见问题和可能的解决方案。
版本冲突
如果两个 NuGet 包依赖于同一个包，但引用了它的不同版本，Unity 会显示类似的错误：
Assembly 'Assets/Packages/System.Diagnostics.EventLog.4.7.0/lib/netstandard2.0/System.Diagnostics.EventLog.dll' will not be loaded due to errors:
System.Diagnostics.EventLog references strong named System.Security.Principal.Windows Assembly references: 4.1.1.0 Found in project: 4.1.3.0.
Assembly Version Validation can be disabled in Player Settings "Assembly Version Validation"
如消息中所述，可以通过更改一个设置来抑制此错误。只需进入“编辑”->“项目设置”->“播放器”，然后向下滚动并展开“其他设置”，在“配置”部分下取消勾选“程序集版本验证”。
播放器设置截图
系统库缺失
当目标框架为 .Net Framework 时，在“编辑”->“项目设置”->“播放器”->“其他设置”下的“API 兼容性级别”设置为 .NET Framework，Unity 默认不会包含某些系统库。更多关于系统库的信息，请参考Unity 关于系统库的文档以及Unity 关于 .Net 配置支持的文档。默认未导入的库包括 System.Drawing、System.IO.Compression、System.IO.Compression.FileSystem 和 System.Net.Http 等。如果您尝试使用这些库之一，将会收到一个错误提示：
The type `HttpClient` is defined in an assembly that is not referenced. You must add a reference to assembly 'System.Net.Http, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.
要导入系统库并解决错误，您需要创建一个名为 csc.rsp 的文件，并包含以下内容，例如，若要导入 System.Net.Http。
-r:System.Net.Http.dll
将其放置在需要库的父项目中（例如 Assets 文件夹内）。也可以将其放入包含 .asmdef 文件的文件夹中，以仅向子项目添加引用。例如，NuGetForUnity 也使用了一个 csc.rsp 文件，具体请参见 csc.rsp。