4 种安装特定版本 Package 的方法

引言

在 Unity 项目的开发生命周期中，工具版本的确定性往往比追求最新更为重要。然而，在实际的工程实践中，开发者面临的需求远比「使用最新版本」复杂得多，包括但不仅限于以下情境：

• 团队协作对齐：为了确保所有成员的代码表现一致，必须严格锁定所有 Package 的版本号。
• 老旧项目维护：接手或复现一个两年前的项目时，新版 Package 往往会导致兼容性报错，比如 XRI 2.x 升级到 3.x 的架构断层、API 结构不兼容等。当老项目架构对旧版本 Package 开发依赖严重时，此时回退到旧版本往往是更高效的解决方案。
• 特定环境复现：跟随特定的技术教程学习时（如 XR Interaction Toolkit、ARFoundation 课程），必须使用与之严格匹配的工具版本，才能得到更好的沉浸式学习体验——版本差异会因为命令路径、界面布局的不一致，而导致学习进程的中断。

对于需要在线安装管理的工具包（比如 Interaction Toolkit、ARFoundation 等），Package Manager 的默认策略通常是推荐当前可用的「最新版」。而安装指定版本的 Package 相对比较有挑战性，因为这些工具包通常不提供离线下载文件，所以我们需要掌握在 Package Manager 中安装特定版本的技巧。

适用范围说明

本文讨论的对象是通过 Package Manager 在线安装的工具包 Package（UPM），并非传统意义上的资源包（.unitypackage）。后续也将会使用 Package 指代前者。

此外，部分第三方厂商（如 PICO、Meta 等）提供的 SDK 通常支持离线安装方式，可直接从官方渠道获取历史版本，故不在本文讨论范围内。

四种方法

方法零：通过详情页历史版本安装

在尝试复杂方法前，可先检查 Unity 原生提供的历史列表，在这里 Unity 会提供几个推荐的稳定版本。

操作步骤（以 Unity 2022 为例）

1. 在 Package Manager 中选择目标 Package。
2. 在右侧详情页点击 Version History 选项卡。
3. 如果目标版本在列表中，直接点击右下角的 Update to x.x.x。

提示：此列表通常只显示提供有限数量的版本，如上图所示，以 Interaction Toolkit 为例，仅提供一个降级选项 2.6.5，且没有提供升级选项如 3.3.0 等较高版本。若找不到所需版本，请参考以下方法。

方法一：安装时填写指定

这种方法适用于项目中尚未安装该 Package 的情况，能够在首次安装时直接指定版本，后续无需升降级操作。

操作步骤

1. 在 Package Manager 窗口中，点击左上角的「+」号。
2. 在下拉菜单中选择「Add package by name…」，如图所示：

3. 在弹出的窗口中，分别输入包的完整名称 (Name) 和版本号 (Version)，然后点击 Add。以安装 Interaction Toolkit 为例，填写如下内容：

Name: com.unity.xr.interaction.toolkit
Version: 3.0.3

缺点与挑战

如上图所示，该方法最大的门槛在于：开发者需要准确知道包的完整名称（Name），而这些名称通常类似于命名空间，既冗长又难记，对新手不太友好。

提示：关于 Package 名称的获取，可在 Package 右侧详情页中，找到标题下方一串类似命名空间的斜体字符串，对其进行复制即可。

方法二：通过文档 Changelog 安装

针对手动输入包名容易出错的问题，我们可以利用各 Package 官方文档中的「快捷链接」来自动填充安装信息。这是一种更为便捷的技巧。

操作步骤

1. 在 Package Manager 中选中目标 Package（无论安装与否），点击详情页中的「Changelog」链接，跳转至网页版官方文档，如下图所示：

2. 在文档页面的左侧版本列表中，找到并点击需要安装的目标版本。

3. 在对应版本的更新说明顶部，找到类似 “Add version x.x.x by name” 的链接按钮，如下图所示（以 3.0.6 为例）：

4. 点击该链接，浏览器会请求打开 Unity Editor。允许后，自动跳转到 Unity 编辑器中，会自动弹出 Add package by name 窗口，并自动填充好准确的包名和版本号，然后直接点击 Add 即可。

优缺点分析

• 优点：无需手动输入冗长的包名，彻底避免拼写错误，操作流畅便捷。
• 潜在问题：极少数情况下（例如 XRI 3.0.4 等特定版本），可能会出现文档链接与服务器资源不同步的情况，导致点击后安装报错。但这通常是个例，后续官方可能也会根据反馈修正这个问题，绝大多数情况依然推荐使用此方法。

方法三：直接修改 manifest.json 文件

如果已经安装了某个 Package，当需要进行版本升级或降级时，除了在编辑器内操作，还可以通过直接修改项目清单文件（manifest.json）的方式来实现。这种方法适合批量管理依赖或快速复制他人的环境配置。

操作步骤

1. 在 Project 窗口中，右键点击 Packages 文件夹，选择 “Reveal in Finder”（Windows 下为 “Show in Explorer”）。

2. 进入打开的文件夹，找到名为 manifest.json 的文件（注意：请勿修改 packages-lock.json），使用任意代码编辑器（如 VS Code）或记事本将其打开。

3. 在清单中找到目标 Package 的名称（例如 com.unity.xr.interaction.toolkit），将其冒号后的版本号手动修改为目标版本。例如，将 XRI 版本选定为 2.6.3，做如下修改：

4. 保存文件并关闭编辑器。返回 Unity 界面，Package Manager 会自动读取最新的清单，并开始解析、下载指定版本的包。

提示：手动修改版本号时需要注意 JSON 语法，必须确保双引号、冒号和行尾的逗号都不缺失且被正确使用。任何一个字符的缺失都会导致 Unity 无法解析配置文件，进而导致编辑器启动时报错。

如何选择合适的方法

作为总结，以下是各方法的使用情境，作为决策参考：

• 方法零：在官方推荐的少数稳定版本之间升降级
• 方法一：首次安装且知道版本号时使用
• 方法二：最推荐的方式，适合大多数场景
• 方法三：批量管理依赖、团队配置同步时使用

另附四种方式的优劣势对比总结：

注意事项

本文介绍的主要内容是如何安装，但这并不意味着在项目中可以随意安装任意版本的 Package。Unity 编辑器版本与 Package 版本之间存在着严格的「伴生关系」，版本过低或过高可能导致 API 不匹配，导致出现大量编译报错而使项目无法正常运行。

• API 匹配：Unity 引擎自身的 API 甚至架构会随版本变动。如果特定版本的 Package 与当前 Unity 引擎不兼容，会导致大量编译错误，项目无法运行。
• 依赖链条：包与包之间也存在依赖关系（例如 XRI 可能依赖特定版本的 Input System 等）。强行修改某一个包的版本，可能会导致整个依赖链断裂。关于包间依赖关系，可在工具包详情页中的 Dependencies 标签页查看，如下图所示：

所以在执行升降级操作前，务必查阅官方文档的兼容性、工具依赖相关章节，确保选择的 Package 版本能够正常使用。

本文首发于微信公众号「XR技术研习社」：阅读原文