源码地址（npm 官方出品）

https://github.com/npm/validate-npm-package-name#naming-rules
检查 npm 包名是否正确合法（Give me a string and I’ll tell you if it’s a valid npm package name.）

源码注释

  1. 'use strict'
  3. var scopedPackagePattern = new RegExp('^(?:@([^/]+?)[/])?([^/]+?)$')
  4. var builtins = require('builtins')
  5. var blacklist = [
  6.   'node_modules',
  7.   'favicon.ico'
  8. ]
  10. var validate = module.exports = function (name) {
  11.   var warnings = []
  12.   var errors = []
  14.   // 判断是否为空，如果为空则为 error 级别错误，直接 return 退出返回，无需继续以下检查
  15.   if (name === null) {
  16.     errors.push('name cannot be null')
  17.     return done(warnings, errors)
  18.   }
  20.   // 判断是否 undefined，error 级别错误，直接 return 返回
  21.   if (name === undefined) {
  22.     errors.push('name cannot be undefined')
  23.     return done(warnings, errors)
  24.   }
  26.   // 判断是否为 string 类型，error 级别错误，直接 return 返回
  27.   // 123 是错误的，'123' 是正确的
  28.   if (typeof name !== 'string') {
  29.     errors.push('name must be a string')
  30.     return done(warnings, errors)
  31.   }
  33.   // 判断长度，如果是 '' 则为 error 级别错误，这里其实也可以直接 return 返回？
  34.   if (!name.length) {
  35.     errors.push('name length must be greater than zero')
  36.   }
  38.   // 判断是否为 . 开头的，error 级别错误，不需要返回，因为还有别的错误要一起检查
  39.   if (name.match(/^\./)) {
  40.     errors.push('name cannot start with a period')
  41.   }
  43.   // 判断是否为 _ 开头的，error 级别错误，不需要返回
  44.   if (name.match(/^_/)) {
  45.     errors.push('name cannot start with an underscore')
  46.   }
  48.   // 判断开头结尾是不是有空格的，error 级别错误，不需要返回
  49.   if (name.trim() !== name) {
  50.     errors.push('name cannot contain leading or trailing spaces')
  51.   }
  53.     // 判断是不是黑名单的关键字，大小写不敏感，统一变成小写来判断，error 级别错误
  54.   // No funny business
  55.   blacklist.forEach(function (blacklistedName) {
  56.     if (name.toLowerCase() === blacklistedName) {
  57.       errors.push(blacklistedName + ' is a blacklisted name')
  58.     }
  59.   })
  61.   // Generate warnings for stuff that used to be allowed
  63.   // 使用 builtins 库，拿到 node core module names 列表
  64.   // 逐个判断是不是有一致的，如果是，则为 warning 级别错误
  65.   // core module names like http, events, util, etc
  66.   builtins.forEach(function (builtin) {
  67.     if (name.toLowerCase() === builtin) {
  68.       warnings.push(builtin + ' is a core module name')
  69.     }
  70.   })
  72.   // 长度不能超过 214 个字符，warning 级别错误
  73.   // really-long-package-names-------------------------------such--length-----many---wow
  74.   // the thisisareallyreallylongpackagenameitshouldpublishdowenowhavealimittothelengthofpackagenames-poch.
  75.   if (name.length > 214) {
  76.     warnings.push('name can no longer contain more than 214 characters')
  77.   }
  79.   // 不能包含大写字符，warning 级别错误
  80.   // mIxeD CaSe nAMEs
  81.   if (name.toLowerCase() !== name) {
  82.     warnings.push('name can no longer contain capital letters')
  83.   }
  85.   // 判断是否包含 ~'!()* 这几个特殊字符，但只是判断 / 后面的
  86.   // 比如 @test/abc 是正确的
  87.   // 比如 @test/ab!!!c 是错误的
  88.   // 比如 @test!!!/abcabfd 是正确的
  89.   if (/[~'!()*]/.test(name.split('/').slice(-1)[0])) {
  90.     warnings.push('name can no longer contain special characters ("~\'!()*")')
  91.   }
  93.   // 判断是否为 scoped package name
  94.   if (encodeURIComponent(name) !== name) {
  95.     // Maybe it's a scoped package name, like @user/package
  96.     var nameMatch = name.match(scopedPackagePattern)
  97.     if (nameMatch) {
  98.       // 如果是 @babel/core，则会 user = babel，pkg = core
  99.       var user = nameMatch[1]
  100.       var pkg = nameMatch[2]
  101.       // 然后使用 encodeURIComponent，判断这俩里面有没有 non-url-safe 字符
  102.       if (encodeURIComponent(user) === user && encodeURIComponent(pkg) === pkg) {
  103.         // 注意这里是全等才进入，说明没有包含 non-url-safe 字符
  104.         // 说明最后的检查已经结束
  105.         return done(warnings, errors)
  106.       }
  107.     }
  109.     // 有可能是正则 mathch 不出来的，就会标为非法，比如 @abc/sfdsa/dsafdsa, @abc/sfdsa@dsafdsa/sdafdsa
  110.     // 也有可能是 match 解析出来之后，user 和 pkg 内包含特殊字符的，比如 @abc/sfdsa@dsafdsa
  111.     errors.push('name can only contain URL-friendly characters')
  112.   }
  114.   // 经过上面一系列判断之后，整体返回 warnings 数组 和 errors 数组
  115.   return done(warnings, errors)
  116. }
  118. // 隐藏功能，提供给私有域定制 npm 设置包名校验规则
  119. validate.scopedPackagePattern = scopedPackagePattern
  121. var done = function (warnings, errors) {
  122.   var result = {
  123.     // 新版本 pkg name 不允许有 errors 和 warnings 错误
  124.     validForNewPackages: errors.length === 0 && warnings.length === 0,
  125.     // 旧版本 pkg name 不允许有 errors 错误，可以忽略 warnings 错误
  126.     validForOldPackages: errors.length === 0,
  127.     // warnings message
  128.     warnings: warnings,
  129.     // errors message
  130.     errors: errors
  131.   }
  132.   if (!result.warnings.length) delete result.warnings
  133.   if (!result.errors.length) delete result.errors
  134.   return result
  135. }

深究细节

1. 判断逻辑

  • 比较明显能直接返回的错误，会写在前面，比如 null，undefined，非 string 判断这种
  • 除了直接 return 的下面所有 if 校验，会一条条叠加判断，有可能会命中多条，比如有可能字符会超过 214，同时又包含特殊字符，又包含大写字符等。这样一次性就能返回给开发者所有错误信息。
  • if (encodeURIComponent(user) === user && encodeURIComponent(pkg) === pkg) 这段的判断可能会有点点绕，是不包含 non-url-safe 字符才进入

    2. module exports 暴露的 validate

    最后一句有句 validate.scopedPackagePattern = scopedPackagePattern，具体作用是？

    3. encodeURIComponent 和 encodeURI 区别

    encodeURIComponent 比 encodeURI 编码范围更大，比如 http://，encodeURIComponent 会编码成 http%3A%2F%2F，encodeURI 不会

    4. 如何判断 node core module names

    使用 builtins 这个包，https://www.npmjs.com/package/builtins，里面逻辑也比较简单，返回的是 string array，https://github.com/juliangruber/builtins/blob/master/index.js，包含的是 core module name

5. 正则

new RegExp(‘^(?:@([^/]+?)[/])?([^/]+?)$’)，@ 和 / 之间的是 group1，/ 之后的是 group2
截屏2021-10-10 上午12.24.27.png
这里有个特殊字符，?:@，可以对比看看没有 ?: 是怎么样的，new RegExp(‘^(@([^/]+?)[/])?([^/]+?)$’)，如下图，会多匹配出一个 group
截屏2021-10-10 上午12.27.59.png
截屏2021-10-10 上午12.29.49.png
test 一下几个 case（对着图示分析，总的来说，能根据字符串能完整走一个通路，就说明能匹配，否则为 null）：

  • ‘@demo/test’.match(new RegExp(‘^(?:@([^/]+?)[/])?([^/]+?)$’))，匹配出 user(group1) = ‘demo’，pkg(group2) = ‘test’
  • ‘/d’.match(new RegExp(‘^(?:@([^/]+?)[/])?([^/]+?)$’))，调用 match 返回 null
  • ‘@user’.match(new RegExp(‘^(?:@([^/]+?)[/])?([^/]+?)$’))，匹配出 user(group1) = undefined, pkg(group2) = ‘@user’

应用场景

https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli/lib/create.js#L20
比如 vue-cli create，Error 错误看出来是 validate-npm-package-name 透传出来的错误信息，拼接之后直接展示：
截屏2021-10-09 下午7.06.23.png
对应代码：

  1. // ...
  3. // 引用包
  4. const validateProjectName = require('validate-npm-package-name')
  6. async function create (projectName, options) {
  7.   if (options.proxy) {
  8.     process.env.HTTP_PROXY = options.proxy
  9.   }
  11.   const cwd = options.cwd || process.cwd()
  12.   const inCurrent = projectName === '.'
  13.   const name = inCurrent ? path.relative('../', cwd) : projectName
  14.   const targetDir = path.resolve(cwd, projectName || '.')
  16.   // 调用库校验
  17.   const result = validateProjectName(name)
  19.   // 如果检验不通过，逐行显示错误信息，最后 exit(1) 退出程序
  20.   if (!result.validForNewPackages) {
  21.     console.error(chalk.red(`Invalid project name: "${name}"`))
  22.     result.errors && result.errors.forEach(err => {
  23.       console.error(chalk.red.dim('Error: ' + err))
  24.     })
  25.     result.warnings && result.warnings.forEach(warn => {
  26.       console.error(chalk.red.dim('Warning: ' + warn))
  27.     })
  28.     exit(1)
  29.   }
  31.   // ...

附录