跳到主要内容
版本号：6.x

配置文件

此文件是 Verdaccio 的重要部分, 您可以在其中修改默认行为, 启用插件并扩展功能。

首次运行 Verdaccio 时会自动生成默认的配置文件 config.yaml。

默认配置​

默认配置支持 私有（scoped） 包，并允许所有用户 访问 所有包，但只有已登陆用户才能 发布。

storage: ./storage
auth:
  htpasswd:
    file: ./htpasswd
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    proxy: npmjs
log: { type: stdout, format: pretty, level: http }

章节​

以下各章节解释了每个属性的含义以及不同的选项。

存储​

是默认的存储方式。 Verdaccio 默认使用内置本地文件模式存储 。

storage: ./storage

V5.6.0 发布：环境变量 VERDACCIO_STORAGE_PATH 可用于替换存储的位置（仅适用于默认存储，不适用于插件，除非它独立实现）。

.verdaccio-db 数据库​

微型数据库用于存储用户发布的私有包。 该数据库基于 JSON 文件，其中包含已发布的私有包列表以及用于令牌签名的秘密令牌。 首次启动应用程序时会自动创建。

数据库的位置基于 config.yaml 文件夹位置，例如：

如果 config.yaml 位于 /some_local_path/config.yaml，则数据库将在 /some_local_path/storage/.verdaccio-db 中创建。

信息

对于长期使用 Verdaccio 且 .verdaccio-db 文件已经存在的用户，密钥长度可为 64 个字符。 但是，对于较新的安装，长度将生成为 32 个字符长。

如果密钥长度为64 个字符：

  • 对于在 Node.js 22 或更高版本上运行 Verdaccio 5.x 的用户，如果密钥长度不是 32 个字符长的，应用程序将无法启动。
  • 对于在 Node.js 21 或更低版本上运行 Verdaccio 5.x 的用户，应用程序可以启动，但会在控制台显示弃用警告。

如何升级存储中的令牌密钥？​

⚠️ 如果更新密钥将使所有先前生成的令牌失效。

选项 1：手动​

转至存储位置并手动将密钥修改为 32 个字符长。

选项 2：自动（自 v5.31.0 起）​

如果长度为 64 个字符，则 migrateToSecureLegacySignature 属性用于生成新的密钥令牌。

security:
  api:
    migrateToSecureLegacySignature: true

令牌将自动更新为 32 个字符，应用程序将顺利启动。 该属性不会对应用程序产生任何其他影响，并且可以在更新密钥后删除。

.verdaccio-db文件数据库只有在用户不使用自定义存储时可用，默认情况下，verdaccio 使用一个小型数据库来存储私有软件包，storage属性定义在 config.yaml 文件中。 根据操作系统的不同，位置可能会有所变化。 阅读 CLI 部分 以获取有关文件位置的更多详细信息。

数据库的结构基于 JSON 文件，例如：

{
  "list": ["package1", "@scope/pkg2"],
  "secret": "secret_token_32_characters_long"
}
  • list: 是一个数组，包含已发布的私有包的列表，这个列表上的任何项目都被认为是由用户发布的。
  • secret：secret 字段用于令牌签名和验证，适用于 JWT 或 legacy 令牌签名。

插件​

插件目录的位置。 对于基于 Docker/Kubernetes 的部署很有用。

plugins: ./plugins

认证​

在这里进行身份验证设置。 默认认证基于 htpasswd，并且是内置的。 你可以通过插件来修改这一行为。 有关此部分的更多信息，请阅读授权页面。

auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000

安全​

安全配置允许使用两个选项自定义令牌签名。 配置分为两个部分：api 和 web。 在使用 JWT 时，api 必须定义；否则，将使用 Legacy 令牌签名（aes192）。

token 是如何生成的？​

令牌签名需要由创建 .verdaccio-db 数据库的自定义插件生成的秘密令牌，或者在使用自定义存储的情况下，秘密令牌是从插件实现本身获取的。 无论如何，启动应用程序都需要秘密令牌。

Legacy 令牌签名​

legacy 属性用于启用旧令牌签名。 默认情况下启用。 Legacy 功能仅应用于 API，Web UI 默认使用 JWT。

信息

在使用 Node.js 21 或更低版本的 5.x 版本中，将会看到警告 [DEP0106] DeprecationWarning: crypto.createDecipher is deprecated。 打印在终端中。 此警告表明 Node.js 已弃用 legacy 签名所使用的函数。

如果 verdaccio 在 Node.js 22 或更高版本上运行，您将不会看到此警告，因为已经实现了新的 Legacy 签名。

migrateToSecureLegacySignature 属性仅适用于高于 5.31.0 的版本，并且默认为 false。

security:
  api:
    legacy: true # 默认情况下为 true，即使此部分未定义
    migrateToSecureLegacySignature: true # 如果长度为 64 个字符，将生成一个新的加密令牌

JWT 令牌签名​

要启用新的 JWT（JSON Web令牌） 签名，需要将 jwt 块添加到 api 部分； web 中默认使用 jwt。

通过使用 JWT 签名，还可以使用自己的属性来自定义签名和令牌验证。

security:
  api:
    legacy: true
    migrateToSecureLegacySignature: true # will generate a new secret token if the length is 64 characters
    jwt:
      sign:
        expiresIn: 29d
      verify:
        someProp: [value]
   web:
     sign:
       expiresIn: 1h # 1 hour by default
     verify:
        someProp: [value]

服务器​

一组用于修改服务器应用程序行为的属性，特别是 API（Express.js）。

您可以为传入连接指定 HTTP/1.1 服务器保 Keep-Alive 超时（以秒为单位）。 值 0 使 http 服务器的行为与 8.0.0 之前的 Node.js 版本类似，后者没有 Keep-Alive 超时时间。 解决方法：通过给定的配置，您可以解决以下问题 https://github.com/verdaccio/verdaccio/issues/301。 如果 60 不够，则设置为 0。

server:
  keepAliveTimeout: 60

Web UI​

此属性允许您修改 Web UI 的外观。 有关本节的更多信息，请阅读 web UI 页面。

web:
  enable: true
  title: Verdaccio
  logo: logo.png
  scope:

当这些包在本地不可用时，上行链路增加了从远程注册表获取包的功能。 有关本节的更多信息，请阅读上行链接页面。

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

软件包​

本部分允许您控制软件包的访问方式。 有关本部分的更多信息，请阅读 软件包页面。

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs

高级设置​

离线发布​

默认情况下，verdaccio 不允许你在客户端离线时发布软件包。 可以通过将该值设置为 true 来覆盖此设置。

publish:
  allow_offline: false
Since: verdaccio@2.3.6 due #223

URL 前缀​

该前缀用于服务器在代理之后运行时使用，如果在没有反向代理的情况下使用，则无法正常工作，请查看 反向代理设置 页面了解更多详细信息。

内部逻辑正确构建了公共 URL，验证了 host 标头和错误的 url_prefix。

例如：url_prefix: /verdaccio, url_prefix: verdaccio/, url_prefix: verdaccio 将转换为 /verdaccio/

url_prefix: /verdaccio/

新的 VERDACCIO_PUBLIC_URL 用于代理后，该变量将用于：

  • 用作提供 UI 资源（js、favicon 等）的基本路径
  • 用于返回元数据 dist 基本路径
  • 忽略 host 和 X-Forwarded-Proto 请求头
  • 如果设置了url_prefix则将其追加到环境变量(env) 中。

在环境变量页面阅读更多关于 VERDACCIO_PUBLIC_URL 的信息。

User Agent​

自 verdaccio@5.4.0`

默认情况下，用户代理是禁用的，作为交换，用户代理客户端信息（包管理器、浏览器等）被直接透传到远程服务器。 要启用以前的行为，请使用布尔值。

user_agent: true
user_agent: false
user_agent: 'custom user agent'

用户速率限制​

自: `verdaccio@5.4.0` [#](https://github.com/verdaccio/verdaccio/releases/tag/v5.4.0)

为用户端 npm token、npm profile、npm login/adduser 和登录网站设置默认请求速率限制，以每 15 分钟限制 100 个请求为例，可通过以下方式定制：

userRateLimit:
  windowMs: 50000
  max: 1000

还可以通过中间件文档进行其他配置（仅限功能标志）。

最大请求体大小​

默认情况下，JSON 文档的最大请求体大小为 10mb，如果遇到提示"request entity too large"的错误，你可以增加该值的大小。

max_body_size: 10mb

监听端口​

verdaccio 默认在端口 4873 上运行。 可以通过 CLI 或在配置文件中更改端口。 以下选项是有效的：

listen:
# - localhost:4873            # default value
# - http://localhost:4873     # same thing
# - 0.0.0.0:4873              # listen on all addresses (INADDR_ANY)
# - https://example.org:4873  # if you want to use https
# - "[::1]:4873"                # ipv6
# - unix:/tmp/verdaccio.sock    # unix socket

HTTPS​

要在 verdaccio 启用 https，只要用 https:// 协议来设置 listen 标志。 如需了解更多信息，请阅读文档中的 SSL 部分

https:
  key: ./path/verdaccio-key.pem
  cert: ./path/verdaccio-cert.pem
  ca: ./path/verdaccio-csr.pem

代理​

代理是特殊用途的 HTTP 服务器，用于将数据从远程服务器传输到本地客户机。

http_proxy 和 https_proxy​

如果你的网络中有一个代理，你可以使用以下属性设置 X-Forwarded-For 报头：

http_proxy: http://something.local/
https_proxy: https://something.local/

no_proxy​

此变量应包含一个逗号分隔的不应用于代理的域扩展列表。

no_proxy: localhost,127.0.0.1

通知​

通过 webhook 启用对第三方工具的通知相当容易。 有关此部分的更多信息，请阅读通知页面。

notify:
  method: POST
  headers: [{ 'Content-Type': 'application/json' }]
  endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
  content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'

如需了解更详细的配置设置，请查看源代码。

日志​

风险

自 v5.22.0 以来，logger 属性被重新命名为 logs，但 log 仍然兼容，但显示一个警告

支持两种记录器类型，您可以只选择其中一种：

控制台输出 (默认)​

log: { type: stdout, format: pretty, level: http }

文件输出​

log: { type: file, path: verdaccio.log, level: info }

有关完整信息-请参阅此处：Features/logger

Audit​

自 verdaccio@3.0.0`

npm audit 是随 npm 6.x 发布的一项新命令。 Verdaccio 包含一个内置中间件插件来处理此命令。

使用新的安装方式会默认包含这个中间件，否则你需要添加下面这些属性到你的配置文件中

middlewares:
  audit:
    enabled: true
    # timeout: 10000

实验性​

此版本包含一个名为 experiments 的新属性，可以放置在 config.yaml 中，并且完全是可选的

我们希望能够在不影响生产环境的情况下发布新特性。 此标志允许我们添加新功能并从决定使用它们的社区获得反馈。

此标志下的功能可能不稳定或者可能会在未来的版本中被删除。

以下是一个例子：

experiments:
  changePassword: false

要禁用控制台中的实验警告，你必须注释掉整个实验部分。

配置生成器 API​

在v5.23.1版本之后，新的高级配置构建器 API 可用。 该 API 是一种灵活的方式，可以使用构建器模式以 JSON 或 YAML 形式以编程方式生成配置输出，例如：

import { ConfigBuilder } from 'verdaccio';

const config = ConfigBuilder.build();
config
  .addUplink('upstream', { url: 'https://registry.upstream.local' })
  .addUplink('upstream2', { url: 'https://registry.upstream2.local' })
  .addPackageAccess('upstream/*', {
    access: 'public',
    publish: 'foo, bar',
    unpublish: 'foo, bar',
    proxy: 'some',
  })
  .addLogger({ level: 'info', type: 'stdout', format: 'json' })
  .addStorage('/tmp/verdaccio')
  .addSecurity({ api: { legacy: true } });

// generate JSON object as output
config.getConfig();

// generate output as yaml
config.getAsYaml();