Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
 
 
Cannot retrieve contributors at this time

openupm-cli

阅读其他语言的版本:English, 简体中文.

npm NPM npm

openupm-cli是用于维护Unity的manifest.json的命令行工具。可便捷的安装来自第三方upm仓库的软件包。类似于NodeJS生态下的npm或yarn。

虽然该工具的设计初衷是为了配合OpenUPM开源软件仓库使用, 但也可以用于任意的upm软件仓库,包括Unity官方的upm软件仓库。

工作原理

openupm-cli基于Unity对带作用域的软件仓库(scoped registry)的支持。该命令行工具在安装、删除第三方软件时会修改Packages/manifest.json清单文件。Unity会检测到清单文件的修改,并尝试解析、安装软件包。

注意:至少到目前为止,该命令行工具不会直接安装/卸载软件包tarball。

安装

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'

请安装nodejs 14.18或以上版本

中国区

若使用中国区,请使用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_proxyhttps_proxy环境变量,以保证Unity编辑器可以访问您的代理服务器