很多用Verdaccio做私有npm源的开发者，都会踩过package access规则失效的坑——明明配置了某个包的访问权限，却还是能被随便访问，或者需要认证的包反而能匿名拉取，这背后大概率是规则匹配逻辑和通配符的用法没搞对。

一、先搞懂Verdaccio规则失效的常见场景

很多时候规则失效不是Verdaccio的bug，而是开发者没踩对配置的“坑点”，常见的失效场景有两类。

1.1 场景1：精确规则被宽松规则覆盖

比如你要让@myorg/admin这个敏感包只有admin组能访问，却配置了@myorg/*的规则，结果@myorg/admin被@myorg/*的宽松规则匹配了，普通用户也能访问。

1.2 场景2：通配符写法错误导致匹配混乱

比如想匹配@myorg下所有一级包，却写成了@myorg**，结果误匹配了@myorg-other这类非预期的包，或者漏掉了嵌套包的权限。

二、核心问题：匹配优先级到底怎么回事

Verdaccio的package access规则是从上到下遍历匹配的，第一个命中包名的规则会直接生效，不会再往下看其他规则。举个最直白的例子： 你配置了两个规则，第一个是@myorg/，第二个是@myorg/admin。当用户请求@myorg/admin时，Verdaccio先找到第一个匹配的@myorg/，就会用这个规则的权限，完全忽略下面精确的@myorg/admin规则——这就是很多人觉得“精确规则不生效”的核心原因。

三、通配符的正确用法 vs 踩坑案例

Verdaccio里的通配符主要有两种，别搞混用法，不然很容易踩坑。

3.1 两种通配符的正确用法

第一种是*，只匹配当前层级的包路径；第二种是**，匹配包括嵌套在内的所有路径。 举个正确的配置示例（技术栈：Verdaccio 5.x）：

{
  "packages": {
    // 正确用法：@myorg/*匹配@myorg下的一级包，比如@myorg/utils、@myorg/tools
    "@myorg/*": {
      "access": ["dev", "admin"], // 允许dev和admin组访问一级包
      "publish": ["admin"], // 只有admin能发布
      "unpublish": ["admin"] // 只有admin能下架
    },
    // 正确用法：@myorg/**匹配所有嵌套包，比如@myorg/utils/helper
    "@myorg/**": {
      "access": ["admin"], // 嵌套的私有包只允许admin访问
      "publish": ["admin"],
      "unpublish": ["admin"]
    }
  }
}

3.2 踩坑：通配符多写/少写符号

很多人会把@myorg/写成@myorg，少了斜杠，结果变成匹配所有@myorg开头的任意字符，比如@myorgxyz、@myorgadmin，完全不符合预期。

3.3 踩坑：规则顺序搞反

把需要严格控制的精确规则放在了宽松规则的后面，比如把@myorg/admin写在@myorg/*的下面，导致请求时先匹配到宽松规则，精确规则直接失效——这个是最常见的坑，10个规则失效的案例里有8个是这个问题。

四、实际排查案例详解+修复指南

这里拿一个真实的踩坑案例来拆解，帮你一步步排查修复。

4.1 踩坑原配置

{
  "packages": {
    // 宽松规则放在前面，导致精确规则被覆盖
    "@myorg/*": {
      "access": ["$all"], // 所有人都能访问，太宽松
      "publish": ["admin"],
      "unpublish": ["admin"]
    },
    "@myorg/admin": {
      "access": ["admin"], // 只允许admin访问，这个规则没生效
      "publish": ["admin"],
      "unpublish": ["admin"]
    }
  }
}

4.2 排查步骤

  1. 第一步：看规则顺序：打开Verdaccio的配置文件，发现@myorg/*在@myorg/admin的前面，所以当请求@myorg/admin时，先匹配到@myorg/*的规则，直接用了$all的权限，精确规则自然没用。
  2. 第二步：通配符校验：这里的@myorg/*写法是对的，少了斜杠才会有问题，所以通配符本身没错，问题是顺序。
  3. 第三步：用实际用户测试：切换到普通dev用户，执行npm install @myorg/admin，能成功安装，说明普通用户确实有访问权限，和规则失效的表现一致。

4.3 修复后的配置

只需要把精确规则放在宽松规则的前面，调整顺序即可：

{
  "packages": {
    // 精确规则放在最前面，优先匹配
    "@myorg/admin": {
      "access": ["admin"], // 现在只有admin组能访问
      "publish": ["admin"],
      "unpublish": ["admin"]
    },
    // 宽松规则放在后面，只有没匹配到精确规则的包才会走这个
    "@myorg/*": {
      "access": ["dev", "admin"], // @myorg下的其他一级包允许dev访问
      "publish": ["admin"],
      "unpublish": ["admin"]
    }
  }
}

4.4 二次验证

用dev用户安装@myorg/admin，会返回403 Forbidden；安装@myorg/utils，能正常安装，说明规则生效了。

五、避坑要点总结

5.1 核心规则优先级

精确规则 > 宽松规则，所以一定要把需要严格控制的包规则放在最前面，通配符规则放在后面，别让宽松规则覆盖了精确权限。

5.2 通配符使用注意

  • 要匹配一级包：用@myorg/*（必须带斜杠）；
  • 要匹配所有嵌套包：用@myorg/**；
  • 别漏写斜杠，别把*和**混用。

5.3 测试是关键

写完规则后一定要用不同的用户组测试：比如用普通用户访问敏感包，看是否有权限；用非admin用户尝试发布包，看是否能成功——别只依赖本地配置就上线，很多隐性问题只有测试才会暴露。

5.4 敏感包单独配置

对于核心敏感包（比如admin后台包、支付相关的工具包），别依赖通配符规则，单独写精确规则，把权限收得最严，避免被误匹配。