Version: 2021.1
Creating samples for packages
版本控制

包清单

Unity 使用包清单文件 (package.json) 来管理有关特定包的特定版本的信息。包清单始终位于包的根目录,并且包含有关包的重要信息,例如其注册名称和版本号。包清单还定义了与用户通信的有用信息,例如出现在 UI 中的用户友好名称、包的简要说明以及该包兼容的最低 Unity 版本。

The package manifest uses the JSON (JavaScript Object Notation) syntax to describe what the package contains. The file’s format is similar to npm’s package.json format, but uses different semantics for some of its properties.

The Package Manager reads this manifest to find out what the package contains, how to unpack its contents, and what information to show the user in the Package Manager window. The manifest stores this information in a series of required, mandatory, and optional properties.

Required properties

These properties are required. If they are not present, either the registry refuses the package when it is published, or the Package Manager cannot fetch or load the package.

属性 JSON 类型 描述
name String The officially registered package name. This name must conform to the Unity Package Manager naming convention, which uses reverse domain name notation. For more information about the naming convention, see Naming your package.

Note: This is a unique identifier, not the user-friendly name that appears in the list view on the Package Manager window.
version string 包版本号 (MAJOR.MINOR.PATCH)。

例如,“3.2.1”表示这是第 3 个主要发行版、第 2 个次要发行版和第 1 个补丁。

该值必须遵守语义版本控制。有关更多信息,请参阅版本控制

Mandatory properties

These properties are technically optional, and the Package Manager can still install them in a project even if they do not contain valid values or are missing. However, you should give values for these properties, to make your package easily discoverable and provide a better experience for users.

属性 JSON 类型 描述
description String 包的简要描述。这是在 Package Manager 窗口的详细信息视图中显示的文本。支持任何 UTF–8 字符代码。这意味着您可以使用特殊格式的字符代码,例如换行符 (\n) 和项目符号 (\u25AA)。
displayName String 一个显示在 Unity Editor 中的用户友好名称(例如,显示在 Project Browser 中、Package Manager 窗口中,等等)。

例如,Unity TimelineProBuilderIn App Purchasing
unity String Indicates the lowest Unity version the package is compatible with. If omitted, the package is considered compatible with all Unity versions.

The expected format is “<MAJOR>.<MINOR>” (for example, 2018.3). To point to a specific patch, use the unityRelease property as well.

Note: A package that is not compatible with Unity will not appear in the Package Manager window.

Optional properties

These properties are optional, meaning that you can omit them. However, if they are present, they must have a valid value.

属性 JSON 类型 描述
author 对象 包的创作者。

该对象包含一个必填字段 (name) 和两个可选字段 (email) 和 (url)。

例如:
{ "name" : "John Doe",
   "email" : "john.doe@example.com",
   "url" : "http://john.doe.example.com/"
}
changelogUrl String Custom location for this package’s changelog specified as a URL. For example:
"changelogUrl": "https://example.com/changelog.html"

Note: When the Package Manager can’t reach the URL location (for example, if there is a network issue), it does the following:

- If the package is installed, it opens a file browser displaying the CHANGELOG.md file in the package cache.
- If the package is not installed, the Package Manager displays a warning that an offline changelog is not available.
dependencies 对象 包依赖关系映射。键是包名称,值是特定版本。它们指示此包依赖的其他包。

注意:Package Manager 不支持范围语法,仅支持 SemVer 版本。
documentationUrl String Custom location for this package’s documentation specified as a URL. For example:
"documentationUrl": "https://example.com/"

Note: When the Package Manager can’t reach the URL location (for example, if there is a network issue), it does the following:

- If the package is installed, it opens a file browser displaying the Documentation~ folder in the package cache.
- If the package is not installed, the Package Manager displays a warning that offline documentation is not available.
hideInEditor Boolean Normally, the Package Manager hides most packages automatically (the implicit value is “true”), but you can set this property to “false” to make sure that your package and its assets are always visible.
keywords 字符串数组 Package Manager 搜索 API 使用的关键字数组。这可以帮助用户找到相关的包。
license String Identifier for an OSS license using the SPDX identifier format, or a string such as “See LICENSE.md file”.

Note: If you omit this property in your package manifest, your package must contain a LICENSE.md file.
licensesUrl String Custom location for this package’s license information specified as a URL. For example:
"licensesUrl": "https://example.com/licensing.html"

Note: When the Package Manager can’t reach the URL location (for example, if there is a network issue), it does the following:

- If the package is installed, it opens a file browser displaying the LICENSE.md file in the package cache.
- If the package is not installed, the Package Manager displays a warning that offline license information is not available.
samples 对象数组 List of samples included in the package. Each sample contains a display name, a description, and the path to the sample folder starting at the Samples~ folder itself:

{
   "displayName": "<name-to-appear-in-the-UI>",
   "description": "<brief-description>",
   "path": "Samples~/<sample-subfolder>"
}

For more information, see Creating samples for packages.
type String 为 Package Manager 提供其他信息的常量。

保留仅供内部使用。
unityRelease String Part of a Unity version indicating the specific release of Unity that the package is compatible with. You can use this property when an updated package requires changes made during the Unity alpha/beta development cycle (for example, if it needs newly introduced APIs, or uses existing APIs that changed in a non-backward-compatible way without API Updater rules).

The expected format is “<UPDATE><RELEASE>” (for example, 0b4).

Note: If you omit the unity property, this property has no effect.

A package that is not compatible with Unity does not appear in the Package Manager window.

包清单示例

{
  "name": "com.unity.example",
  "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.unity.some-package": "1.0.0",
    "com.unity.other-package": "2.0.0"
 },
 "keywords": [
    "keyword1",
    "keyword2",
    "keyword3"
  ],
  "author": {
    "name": "Unity",
    "email": "unity@example.com",
    "url": "https://www.unity3d.com"
  }
}


Creating samples for packages
版本控制