9.3 KiB
openupm-cli
openupm-cli是用于维护Unity的manifest.json的命令行工具。可便捷的安装来自第三方upm仓库的软件包。类似于NodeJS生态下的npm或yarn。
虽然该工具的设计初衷是为了配合OpenUPM开源软件仓库使用, 但也可以用于任意的upm软件仓库，包括Unity官方的upm软件仓库。
工作原理
openupm-cli基于Unity对带作用域的软件仓库（scoped registry）的支持。该命令行工具在安装、删除第三方软件时会修改Packages/manifest.json清单文件。Unity会检测到清单文件的修改，并尝试解析、安装软件包。
注意：至少到目前为止，该命令行工具不会直接安装/卸载软件包tarball。
安装
-
请先自行安装nodejs 14.18或以上版本.
-
通过npm安装：
npm install -g openupm-cli -
或通过yarn安装：
yarn global add openupm-cli
Windows平台故障排除
如果npm在您的命令行环境中不可用，请配置好环境变量.
# npm路径
c:\Program Files\nodejs
# npm全局可执行文件路径
C:\Users\{yourName}\AppData\Roaming\npm
Cannot find module 'node:net' 错误
internal/modules/cjs/loader.js:818
throw err;
^
Error: Cannot find module 'node:net'
中国区
若使用中国区，请使用openupm-cn，或为openupm添加--cn选项。指定中国区后，该命令行将查询Unity中国区域软件仓库（https://packages.unity.cn）和OpenUPM中国区软件仓库（https://package.openupm.cn）。
若使用美股区，请直接使用openupm。
# 例子：查看中国区软件包
openupm view com.littlebigfun.addressable-importer --cn
# 或
openupm-cn view com.littlebigfun.addressable-importer
# 例子：查看美国区软件包
openupm view com.littlebigfun.addressable-importer
指令
添加软件包
openupm-cn add <pkg> [otherPkgs..]
openupm-cn add <pkg>@<version>
openupm-cn add <pkg>@git@github.com:...
openupm-cn add <pkg>@https://github.com/...
openupm-cn add <pkg>@file:...
add指令将软件包添加到manifest.json，并同时维护好作用域（scope）字段。
add指令不会验证或解析Git，HTTPS和文件协议的依赖关系。请参考：https://docs.unity3d.com/Manual/upm-git.html。
add指令不会安装检验失败的软件包：
- 该软件包缺少依赖软件包
- 该软件包指定了一个不存在的依赖软件包版本
- 该软件包需要更高的Unity编辑器版本
您应该手动解决这些问题，或者添加选项-f强制执行。
安装软件包时，您还可以添加将其添加到testables字段：
openupm-cn --test <pkg>
删除软件包
openupm-cn remove <pkg> [otherPkgs...]
搜索软件包
openupm-cn search <keyword>
查看软件包信息
openupm-cn view <pkg>
查看软件包的依赖关系
openupm-cn deps <pkg>
使用选项--deep查看深度依赖关系
openupm-cn deps <pkg> --deep
身份验证
从Unity 2019.3.4f1开始，您可以配置.upmconfig.toml文件以使用私有的软件包仓库。openupm-cn login指令可帮助您通过npm服务器进行身份验证并将信息存储到配置文件中。
使用npm服务器进行身份验证有两种方法：
- 使用令牌验证（推荐的）。
- 使用基本验证：每次发送请求时都发送
用户名:密码的base64编码明文。
验证后，后续的openupm-cli指令将使用.upmconfig.toml配置来访问您的私有软件包仓库。
使用令牌验证
openupm-cn login -u <username> -e <email> -r <registry> -p <password>
# 例如
openupm-cn login -u user1 -e user1@example.com -r http://127.0.0.1:4873
如果缺少所需字段，该指令将提示您输入字段值。如果您的npm服务器不需要电子邮件字段，则可以提供一个虚拟的地址，例如yourname@example.com。请注意，对于大多数npm服务器来说，请求新的令牌并不意味着旧令牌会自动失效。
如果npm服务器允许通过CLI创建用户，提供新的用户名会自动注册一个新的用户。
为了方便起见，令牌也存储在.npmrc文件中。
使用基本验证
添加--basic-auth选项以使用基本验证。
openupm-cn login -u <username> -e <email> -r <registry> -p <password> --basic-auth
# 例如
openupm-cn login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --basic-auth
请注意，使用该指令进行基本验证时，您的用户名和密码的base64编码只是简单的存储在了.upmconfig.toml文件中。我们不会主动的去和npm服务器校验您的密码。因为那样做会导致生成一个验证令牌，这不是您想要的。所以，请务必仔细输入密码。
与使用令牌不同，.npmrc缺乏支持多个软件仓库时指定不同的基本验证信息的语法。因此，.npmrc不会针对基本身份验证进行更新。
始终认证
如果您的软件包仓库的tarball文件位于不同服务器上，则需要添加--always-auth选项。
openupm-cn login -u <username> -e <email> -r <registry> -p <password> --always-auth
# 例如
openupm-cn login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --always-auth
Windows Linux子系统（WSL）
默认情况下，该指令将Windows Linux子系统（WSL）视为Linux系统。但是，如果您想通过Windows进行身份验证（例如，您的Unity编辑器实际安装在window系统中），请添加--wsl选项。
已知问题：使用
--wsl选项运行可能会清除终端屏幕信息。
对Windows系统用户进行身份验证
确保您拥有正确的权限，然后添加--system-user选项以对Windows系统用户进行身份验证。
故障排除
您可以在.upmconfig.toml文件中校验身份验证信息：
- Windows：
%USERPROFILE%/.upmconfig.toml - Windows（系统用户）：
%ALLUSERSPROFILE%Unity/config/ServiceAccounts/.upmconfig.toml - MacOS和Linux：
~/.upmconfig.toml
对于令牌验证，您将看到类似以下信息。
[npmAuth."http://127.0.0.1:4873"]
email = "email address"
alwaysAuth = false
token = "token string"
对于基本验证，您将看到类似以下信息。
[npmAuth."http://127.0.0.1:4873"]
email = "email address"
alwaysAuth = true
_auth = "base64 string"
请注意，软件仓库地址应与您的manifest.json中的信息完全匹配。特别是结束的斜杠，请使用http://127.0.0.1:4873而不是http://127.0.0.1:4873/。
请通过https://forum.unity.com/threads/npm-registry-authentication.836308/了解有关身份验证的更多信息。
指令选项
命令行工具假定当前工作目录（CWD）是Unity项目的根目录（包含Assets文件夹的目录）。但您可以更改当前工作目录。
openupm-cn --chdir <unity-project-path>
指定另一个软件放库（默认为openupm软件仓库）
openupm-cn --registry <registry-url>
# 例如
openupm-cn --registry http://127.0.0.1:4873
显示详细的日志记录
openupm-cn --verbose ...
使用Unity官方软件仓库
如有必要，大多数指令可以访问Unity官方软件仓库，以搜索更多的信息。
$ openupm-cn add com.unity.addressables com.littlebigfun.addressable-importer
added: com.unity.addressables@1.4.0 # 来自Unity软件放库
added: com.littlebigfun.addressable-importer@0.4.1 # 来自OpenUPM软件放库
...
但您也可以关闭这种行为。
openupm-cn --no-upstream ...
使用代理
OpenUPM-CLI支持标准的http_proxy环境变量来指定HTTP，HTTPS或SOCKS代理。
http_proxy="http://127.0.0.1:8080" openupm-cn ...
您可能需要在系统级设置http_proxy和https_proxy环境变量，以保证Unity编辑器可以访问您的代理服务器。