Unity 使用包清单文件 (package.json
) 来管理有关特定包的特定版本的信息。包清单始终位于包的根目录,并且包含有关包的重要信息,例如其注册名称和版本号。包清单还定义了与用户通信的有用信息,例如出现在 UI 中的用户友好名称、包的简要说明以及该包兼容的最低 Unity 版本。
包清单使用 JSON(JavaScript 对象表示法)语法来描述包中所含的内容。该文件的格式类似于 npm 的 package.json
格式,但其某些属性使用了不同的语义。
Package Manager 读取此清单以确认包中所含的内容,如何解压缩其内容,以及在 Package Manager 窗口中向用户显示哪些信息。清单将此信息存储在一系列必需、强制和可选属性中。
这些属性是必需的。如果不存在这些属性,则注册表在发布包时会拒绝该包,或者 Package Manager 无法获取或加载该包。
属性 | JSON 类型 | 描述 |
---|---|---|
name | String | 官方注册的包名称。此名称必须遵循 Unity Package Manager 命名约定,也就是使用反向域名表示法。有关命名约定的更多信息,请参阅为包命名。 注意:这是唯一标识符,而不是出现在 Package Manager 窗口的列表视图中的用户友好的名称。 |
version | string | 包版本号 (MAJOR.MINOR.PATCH)。 例如,“3.2.1”表示这是第 3 个主要发行版、第 2 个次要发行版和第 1 个补丁。 该值必须遵守语义版本控制。有关更多信息,请参阅版本控制。 |
这些属性在技术上是可选的,即使它们不包含有效值或者缺失,Package Manager 仍可以将它们装入到项目中。但是,您应该为这些属性值提供值,以使您的包易于发现,并为用户提供更好的体验。
属性 | JSON 类型 | 描述 |
---|---|---|
description | String | 包的简要描述。这是在 Package Manager 窗口的详细信息视图中显示的文本。支持任何 UTF–8 字符代码。这意味着您可以使用特殊格式的字符代码,例如换行符 (\n) 和项目符号 (\u25AA)。 |
displayName | String | 一个显示在 Unity Editor 中的用户友好名称(例如,显示在 Project Browser 中、Package Manager 窗口中,等等)。 例如,Unity Timeline、ProBuilder 或 In App Purchasing。 |
unity | String | 指示包兼容的最低 Unity 版本。如果省略,则认为该包与所有 Unity 版本兼容。 期望格式为 “<主要版本>.<次要版本>”(例如,2018.3)。要指向特定补丁,还要使用 unityRelease 属性。 注意:与 Unity 不兼容的包将不会出现在 Package Manager 窗口中。 |
这些属性是可选的,这意味着您可以省略它们。但如果存在,则必须具有有效值。
属性 | JSON 类型 | 描述 |
---|---|---|
author | 对象 | 包的创作者。 该对象包含一个必填字段 (name) 和两个可选字段 (email) 和 (url)。 例如: { "name" : "John Doe", "email" : "john.doe@example.com", "url" : "http://john.doe.example.com/" }
|
changelogUrl | String | 此包的变更日志的自定义位置,指定为 URL。例如:"changelogUrl": "https://example.com/changelog.html" 注意:当 Package Manager 无法访问 URL 位置时(例如,如果存在网络问题),它会执行以下操作: - 如果安装了软件包,它会打开一个文件浏览器,显示包缓存中的 CHANGELOG.md 文件。- 如果未安装包,Package Manager 会显示一条警告,指出离线变更日志不可用。 |
dependencies | 对象 | 包依赖关系映射。键是包名称,值是特定版本。它们指示此包依赖的其他包。 注意:Package Manager 不支持范围语法,仅支持 SemVer 版本。 |
documentationUrl | String | 此包的文档的自定义位置,指定为 URL。例如:"documentationUrl": "https://example.com/" 注意:当 Package Manager 无法访问 URL 位置时(例如,如果存在网络问题),它会执行以下操作: - 如果安装了软件包,它会打开一个文件浏览器,显示包缓存中的 Documentation~ 文件夹。- 如果未安装包,Package Manager 会显示一条警告,指出离线文档不可用。 |
hideInEditor | Boolean | 通常,Package Manager 会自动隐藏大多数包(隐式值为 “true”),但您可以将此属性设置为 “false”,确保您的包及其资源始终可见。 |
keywords | 字符串数组 | Package Manager 搜索 API 使用的关键字数组。这可以帮助用户找到相关的包。 |
license | String | OSS 许可证的标识符使用 SPDX 标识符格式,或一个字符串,如 “See LICENSE.md file”。注意:如果您在包清单中省略此属性,则您的包必须包含一个 LICENSE.md 文件。 |
licensesUrl | String | 此包的许可证信息的自定义位置指定为 URL。例如:"licensesUrl": "https://example.com/licensing.html" 注意:当 Package Manager 无法访问 URL 位置时(例如,如果存在网络问题),它会执行以下操作: - 如果安装了软件包,它会打开一个文件浏览器,显示包缓存中的 LICENSE.md 文件。- 如果未安装包,Package Manager 会显示一条警告,指出离线许可证信息不可用。 |
samples | 对象数组 | 包中包含的示例列表。每个示例都包含一个显示名称、一条描述以及示例文件夹的路径,该路径从 Samples~ 文件夹本身开始:{ "displayName": "<name-to-appear-in-the-UI>", "description": "<brief-description>", "path": "Samples~/<sample-subfolder>" } 有关更多信息,请参阅为包创建示例。 |
type | String | 为 Package Manager 提供其他信息的常量。 保留仅供内部使用。 |
unityRelease | String | Unity 版本的一部分,指示与包兼容的特定 Unity 版本。当更新的包需要在 Unity alpha/beta 开发周期中进行更改时(例如,如果该包需要新引入的 API,或该包使用的现有 API 以非向后兼容方式进行更改而不遵循 API Updater 规则),则可以使用此属性。 期望格式为 “<更新><发行版本>”(例如 0b4)。 注意:如果省略 unity 属性,则此属性没有效果。 与 Unity 不兼容的包不会出现在 Package Manager 窗口中。 |
{
"name": "com.[company-name].[package-name]",
"version": "1.2.3",
"displayName": "Package Example",
"description": "This is an example package",
"unity": "2019.1",
"unityRelease": "0b5",
"documentationUrl": "https://example.com/",
"changelogUrl": "https://example.com/changelog.html",
"licensesUrl": "https://example.com/licensing.html",
"dependencies": {
"com.[company-name].some-package": "1.0.0",
"com.[company-name].other-package": "2.0.0"
},
"keywords": [
"keyword1",
"keyword2",
"keyword3"
],
"author": {
"name": "Unity",
"email": "unity@example.com",
"url": "https://www.unity3d.com"
}
}
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.