开发工具CLI【免费下载链接】berry Active development trunk for Yarn ⚒项目地址https://gitcode.com/gh_mirrors/be/berry点击查看免费下载本文是 YarnBerry仓库中 packages/plugin-npm/README.md 的深度展开。该插件是 Yarn 从 npm registry 下载包的核心组件默认内置于 Yarn 发行版中。读完本文你将掌握插件如何在解析/获取阶段接入 npm registry、registry 与认证配置的完整参数体系、元数据缓存与离线模式的工作原理、npm:协议下的三种解析器分工、npm 发布流程含签名与 provenance以及基于发布时间的最小发布年龄安全门控机制及其绕过选项。插件定位Yarn 与 npm registry 之间的桥梁yarnpkg/plugin-npm的职责一句话即可概括为 Yarn 增加从 npm registry 下载包的能力This plugin adds support for downloading packages from the npm registry.。它是 Yarn 生态中最基础的插件之一——绝大部分项目依赖都来自 npm registry因此该插件在 Yarn 中默认启用用户无需手动安装# 插件已内置无需执行任何安装步骤 yarn install从仓库元数据packages/plugin-npm/package.json可以看到它的依赖组成核心依赖yarnpkg/corepeerDependencies提供解析/获取框架semver负责版本区间匹配ssri用于生成 SRI 完整性摘要sigstore用于生成软件供应链 provenance 签名enquirer用于交互式 OTP 输入。这些依赖与下文各功能一一对应。插件在 Yarn 的 Plugin 体系里注册了 2 个 Fetcher 与 3 个 Resolver见 packages/plugin-npm/sources/index.tsFetchersNpmHttpFetcher按显式归档 URL 下载、NpmSemverFetcher按标准 tarball URL 下载ResolversNpmTagResolvernpm:latest等 dist-tag、NpmSemverResolvernpm:^1.0.0等 semver 区间、NpmRemapResolvernpm:other-pkg^1.0.0这种引用其他包的重映射描述符。核心协议npm:前缀与解析-获取流水线所有 npm 来源的依赖在锁文件yarn.lock中都带有npm:协议前缀该协议名定义在 packages/plugin-npm/sources/constants.tsexport const PROTOCOL npm:。一次yarn install的解析链路大致为Tag 解析NpmTagResolver当依赖写成npm:latest、npm:beta这类 dist-tag 时插件读取 registry 元数据中的dist-tags字段把 tag 翻译成具体版本号生成npm:1.2.3形式的 locatorSemver 解析NpmSemverResolver当依赖写成npm:^1.0.0时拉取该包完整版本列表用semver区间过滤出候选版本按版本从高到低排序Remap 解析NpmRemapResolver当描述符写成npm:other-package^1.0.0一个包依赖另一个包时把描述符重映射为另一个包的描述符再交给下层解析器获取NpmSemverFetcher/NpmHttpFetcher根据 locator 拼接 tarball URL 下载.tgz再通过tgzUtils.convertToZip转换为 Yarn 的 zip 缓存格式。注意一个细节tag 与 remap 解析器在supportsLocator中直接返回false见 NpmTagResolver.ts注释明确写着一旦转换成 locator就交给 NpmSemverResolver 处理。因此最终落到磁盘的 locator 永远是一个明确的 semver 版本。semver 区间匹配的细节与边界情况NpmSemverResolver中的selectMatchingVersionsNpmSemverResolver.ts值得单独说明当范围是裸*且没有任何稳定版本匹配时它会放宽到容忍 prerelease 版本再试一次。这是因为 npm 上存在只有预发布版本的包而 semver 语义默认不匹配 prerelease。该行为特意限定在*范围内避免改变其他区间的语义对应 issue #6469。另外在resolve阶段NpmSemverResolver.ts 有一段兼容性补丁npm registry 会在元数据中为存在binding.gyp但没有 install script 的包自动注入node-gyp rebuild插件在解析时扫描scripts若出现node-gyp或prebuild-install且依赖中缺失node-gyp会自动补上node-gyplatest依赖保证原生模块在 PnP 环境下也能顺利构建。配置体系registry、scope、认证与发布参数插件在 packages/plugin-npm/sources/index.ts 中声明了完整配置项。以下按组列出均可写入项目.yarnrc.ymlregistry 相关registrySettings配置项类型默认值说明npmRegistryServerSTRINGhttps://registry.yarnpkg.com默认 npm registry 地址Yarn 官方 registry 会代理 npmjs.org不支持 npm enterprisenpmAuditRegistrySTRINGnull查询安全审计报告所用的 registrynpmPublishRegistrySTRINGnull发布包时推送的目标 registry认证相关authSettings配置项类型默认值说明npmAlwaysAuthBOOLEANfalse是否始终携带认证头对应 npm 的always-authnpmAuthIdentSECRETnull基础认证身份user:pass对应 npm/yarn v1 的_authnpmAuthTokenSECRETnullBearer token对应 npm/yarn v1 的_authToken安全门控相关scopablePackageGateSettings / globalOnlyPackageGateSettings配置项类型默认值说明npmMinimalAgeGateDURATION1d包版本的最小发布年龄单位分钟粒度低于该年龄的版本被隔离不可安装npmPreapprovedPackagesSTRING[][]免于年龄检查的包描述符或 glob 模式列表按 scope 与按 registry 的细分配置插件还支持两级更精细的配置npmScopesMAPkey 为 scope 名每个包 scope 可独立覆盖npmAlwaysAuth、npmAuthIdent、npmAuthToken、npmPublishRegistry、npmRegistryServer、npmMinimalAgeGate。例如私有的mycompany/*包可以指向内部 registrynpmRegistriesMAPkey 为 registry URL按 registry 覆盖认证三件套npmAlwaysAuth、npmAuthIdent、npmAuthTokenkey 会经过normalizeRegistry规范化去除末尾斜杠。配置优先级方面从 npmConfigUtils.ts 的getAuthConfiguration可以看出scope 级认证优先于 registry 级registry 级优先于全局配置getPublishRegistryL23-L31则按publishConfig.registry→ scope registry → 默认 registry 的顺序解析发布目标。一个完整的.yarnrc.yml示例# 默认 registryYarn 官方代理 npmRegistryServer: https://registry.yarnpkg.com # 认证优先级npmScopes npmRegistries 全局 npmAuthToken: npm_xxxxxxxxxxxxxxxx npmAlwaysAuth: false # 发布配置 npmPublishRegistry: https://registry.npmjs.org npmPublishAccess: public # 按 scope 覆盖 npmScopes: mycompany: npmRegistryServer: https://npm.mycompany.com npmAuthToken: private-token-abc npmPublishRegistry: https://npm.mycompany.com npmAlwaysAuth: true # 按 registry 覆盖 npmRegistries: https://registry.npmjs.org: npmAuthToken: npm_yyyyyyyyyyyyyyyy # 安全门控默认 1 天对 trusted-* 包放行 npmMinimalAgeGate: 1d npmPreapprovedPackages: - trusted-* - left-pad^1.0.0元数据缓存与离线模式npm registry 的包元数据版本列表、dist-tags、发布历史在 npmHttpUtils.ts 中实现了两层缓存进程内内存缓存避免同一进程内对同一包重复发起网络请求磁盘缓存存放在globalFolder/metadata/npm/cacheKey/hostname/name.json并配合 HTTP 条件请求If-None-Match/If-Modified-Since即 ETag 与 Last-Modified做增量校验——服务端返回 304 时直接复用本地缓存体。值得注意的设计npmHttpUtils.ts若锁文件需要刷新project.lockfileNeedsRefresh会刻意绕过磁盘缓存防止用户在 hardened 模式下拿到过期元数据离线模式enableOfflineMode下插件会把缓存元数据中本地镜像缺失的版本全部剔除并同步修正dist-tags.latest指向仍可下载的最高版本避免解析器解析出无法下载的版本。另外pickPackageMetadataL293-L302只保留解析/获取所需字段name、dist.tarball、bin、scripts、os/cpu/libc、各类依赖与deprecated等大幅缩小缓存体积。认证链路token、Basic、OTP 与 OIDC插件在发起 registry 请求时通过getAuthenticationHeadernpmHttpUtils.ts构造认证头优先级为插件 HookgetNpmAuthenticationHeader定义于 index.ts允许其他插件动态提供认证头例如对接 CLI 凭据管理器npmAuthToken生成Bearer tokennpmAuthIdent若包含:则 base64 编码为Basic头否则原样使用OIDCallowOidc且未配置静态凭据时通过getOidcToken向 registry 的/-/npm/v1/oidc/token/exchange/package...端点换取临时 Bearer token——支持 GitHub Actions利用ACTIONS_ID_TOKEN_REQUEST_URL、GitLab CI、CircleCI 环境变量。认证类型由AuthType枚举NO_AUTH/BEST_EFFORT/CONFIGURATION/ALWAYS_AUTH控制普通下载走CONFIGURATION仅当npmAlwaysAuth为 true 才带认证头发布publish请求默认走ALWAYS_AUTH确保发布时必须认证。401 响应会被统一转译为AUTHENTICATION_INVALID错误并调用whoami帮助定位是哪个用户身份出错。发布时若 registry 要求两步验证post/put/del请求会解析WWW-Authenticate头中的otp方法在交互式终端中提示输入一次性密码askForOtp并携带npm-otp头重试测试环境则读取YARN_INJECT_NPM_2FA_TOKEN注入。下载 tarball 的两个 FetcherNpmSemverFetcher标准 tarball URL对于常规 registrygetLocatorUrlNpmSemverFetcher.ts按 npm 规范拼接 tarball 地址registry/encoded-name/-/encoded-name-version.tgz例如https://registry.yarnpkg.com/is-number/-/is-number-2.0.0.tgz。下载时有一个细节某些 npm registry 不支持%2f编码的 scope 路径第一次请求失败后会降级把%2f替换回/重试见 L55-L64 的注释与代码。isConventionalTarballUrlL73-L90则判断 registry 返回的dist.tarball是否就是标准 URL若是则 locator 无需携带__archiveUrl参数否则把归档 URL 绑定到 locator 上。NpmHttpFetcher非标准归档 URL当包托管在 CDN 或其他自定义地址registry 元数据里的dist.tarball不是标准 URL时NpmHttpFetcher接管下载NpmHttpFetcher.ts直接请求 locator 中__archiveUrl参数指定的地址同样经tgzUtils.convertToZip转换后落入 Yarn 缓存。这样既保持锁文件可复现又兼容了非标准托管。两个 Fetcher 均通过opts.cache.fetchPackageFromCache走统一的 Yarn 全局缓存命中则上报 Cache Hit未命中则从远端下载并记录 checksum。发布能力npmPublishUtils 与供应链安全除了下载插件还承担yarn npm publish的底层逻辑。makePublishBodynpmPublishUtils.ts构造发布请求体关键点包括用ssri计算 tarball 的sha1shasum与 sha512integrity供 registry 校验打包清单由plugin-pack的packUtils.genPackageManifest生成并附带gitHeadgit rev-parse HEAD便于追溯访问级别manifest.publishConfig.access→ 配置npmPublishAccess→ 默认规则scope 包restricted非 scope 包publicProvenance 支持启用后为发布包生成pkg:npm/nameversion的签名主题subject用sigstore生成 provenance bundle并作为*-sigstore附件随包一起上传。这部分代码正是 README Attribution 一节所声明的来源provenance 逻辑改编自 npm/cli 的 libnpmpublishISC License。README 原文即注明了该归属Provenance code adapted from npm/cli... under ISC license仓库内 npmProvenance.ts 即为对应实现文件。安全门控最小发布年龄Minimal Age Gate这是一个值得单独展开的安全特性。npm registry 元数据中的time字段记录了每个版本的发布时间插件据此实现npmMinimalAgeGate默认1d即发布不足 1 天的版本默认不可安装用于防御供应链投毒——攻击者常利用新发布的恶意版本在短时间内被大量安装。判定逻辑在 npmConfigUtils.tsshouldBeQuarantined比较now - publishTime与门限不足则判定为应隔离isPackageApproved!shouldBeQuarantined() || isPreapproved()——被隔离的版本除非在npmPreapprovedPackages白名单中否则不可用。白名单支持包名描述符与 glob 模式可以是release-date包名、release-date^1.0.0带版本区间、scoped/*scope glob、release-*通配符。scoped 包的npmScopes配置还可以按 scope 覆盖全局门限收紧或放宽均支持且互不泄漏。该行为在测试套件 packages/acceptance-tests/pkg-tests-specs/sources/features/npmMinimalAgeGate.test.ts 中有系统验证覆盖场景包括yarn add/yarn install/yarn up含-R递归下的门限行为精确版本release-date1.1.1过新时报错All versions satisfying 1.1.1 are quarantined范围依赖自动回退到满足年龄的次新版本npmPreapprovedPackages的 descriptor / ident / glob 三种白名单形态scope 级覆盖与全局值的关系--no-time-gate选项在add/up命令上显式跳过年龄检查临时安装刚发布的新版本。对应地NpmSemverResolver.getCandidatesNpmSemverResolver.ts在过滤候选版本后若发现全部被隔离会抛出REMOTE_NOT_FOUND错误NpmTagResolverNpmTagResolver.ts对latesttag 同样执行年龄检查若latest过新则自动回退到次新且通过检查的版本无可用版本时报错。常见运维场景速查场景操作/配置切换默认 registry.yarnrc.yml设置npmRegistryServer使用私有 scope registrynpmScopes: { mycompany: { npmRegistryServer: ... } }配置发布凭据npmPublishRegistrynpmAuthToken下载私有包认证npmAuthTokenBearer或npmAuthIdentBasic跳过最小年龄门禁yarn add --no-time-gate pkg白名单信任新版本npmPreapprovedPackages: [my-org/*]查看缓存位置globalFolder/metadata/npm/元数据与全局 zip 缓存包内容小结yarnpkg/plugin-npm虽然 README 仅三言两语却是 Yarn 生态中承担 npm registry 集成重任的核心插件它定义了npm:协议与五类解析/获取器、提供了从全局到 scope/registry 粒度的完整配置体系、实现了带条件请求的元数据缓存与离线支持、覆盖 token/Basic/OTP/OIDC 的认证矩阵并内置了最小发布年龄这一供应链安全门控。理解它的工作方式既能帮助你排查依赖解析与认证问题也能让你更安全、更精细地管理企业级 registry 集成。赞分享开发工具CLI【免费下载链接】berry Active development trunk for Yarn ⚒项目地址https://gitcode.com/gh_mirrors/be/berry点击查看免费下载相关推荐Yarn Berry 的 npm 命令插件 yarnpkg/plugin-npm-cli发布、登录、审计与标签管理实战指南Yarn Berry 的 npm 命令插件 yarnpkg/plugin npm cli发布、登录、审计与标签管理实战指南 本篇技术指南以 Yarn 仓库中开发工具CLInpm ping 命令深度解析验证 npm registry 连通性与认证状态npm ping 命令深度解析验证 npm registry 连通性与认证状态 npm ping 是 npm 提供的一个轻量级网络诊断命令用于向 配置的或指开发工具包管理器CLIuWebSockets.js 安全发布与直接安装指南NPM Registry 之外的可验证供应链uWebSockets.js 安全发布与直接安装指南NPM Registry 之外的可验证供应链 导读 本指南基于 uWebSockets.js 仓库的 mi后端Web框架WebSocket上一篇终极解决方案3步彻底告别Windows程序缺少DLL错误下一篇bash-it源码架构深度解析揭开bash_it.sh与reloader的模块化加载机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考