validate-npm-package-name 源码阅读

validate-npm-package-name 这个 npm 包的作用就是验证项目名称 (npm 包名) 是否合法，很多的 cli 工具都有使用。例如

vue-cli: https://github.com/vuejs/vue-cli/blob/HEAD/packages/@vue/cli/lib/create.js#L8

create-react-app: https://github.com/facebook/create-react-app/blob/04482a6c2c6639c19deb330c48e4fa5573a1654e/packages/create-react-app/createReactApp.js#L48

vue-cli 的用法如下

const result = validateProjectName(name)
// 名字不合法
if (!result.validForNewPackages) {
  // 输出错误信息
  console.error(chalk.red(`Invalid project name: "${name}"`))
  result.errors && result.errors.forEach((err) => {
    console.error(chalk.red.dim("Error: " + err))
  })
  result.warnings && result.warnings.forEach((warn) => {
    console.error(chalk.red.dim("Warning: " + warn))
  })
  // 结束进程
  exit(1);
}

README

从README中我们可以了解到这是一个检验npm包名是否合法的库。

这个库只导出了一个方法，接收一个字符串即待判断的包名，并返回一个如下格式的对象：

validForNewPackages :: Boolean
validForOldPackages :: Boolean

源码

在index.js中导出的方法是 validate，我们先看看其他逻辑，再看这个核心方法。

直接上源码：

// 检测scoped package name, 比如 `@user/package`
var scopedPackagePattern = new RegExp('^(?:@([^/]+?)[/])?([^/]+?)$')
// builtins是一个json文件，包含一些核心包名的数组，新的npm包名不能和这些重复
var builtins = require('builtins')
// 黑名单，也是不能用的包名
var blacklist = [
  'node_modules',
  'favicon.ico'
]
// 先不看
var validate = module.exports = function (name) {
// ...
}
// 在 `validate` 上挂载 `scopedPackagePattern` 方法，这个可以方便私域定制npm发布设置校验规则

validate.scopedPackagePattern = scopedPackagePattern

/* 这个方法接受 `warnings` 和 `errors` 两个数组，表示警告和错误的数组
 * 如果 `warnings` 和 `errors` 都没有元素，那么 `validForNewPackages` 为true
 * 如果 `errors` 没有元素，那么 `validForOldPackages` 为true
 */
var done = function (warnings, errors) {
  var result = {
    validForNewPackages: errors.length === 0 && warnings.length === 0,
    validForOldPackages: errors.length === 0,
    warnings: warnings,
    errors: errors
  }
  if (!result.warnings.length) delete result.warnings
  if (!result.errors.length) delete result.errors
  return result
}

了解了这些方法之后我们再看 validate 这个方法就很明朗了，在进行了空校验和类型校验之后针对包名的每一个点进行逐个校验。

var validate = module.exports = function (name) {
  var warnings = []
  var errors = []
    
  // 首先进行的是空校验和类型校验
  if (name === null) {
    errors.push('name cannot be null')
    return done(warnings, errors)
  }

  if (name === undefined) {
    errors.push('name cannot be undefined')
    return done(warnings, errors)
  }

  if (typeof name !== 'string') {
    errors.push('name must be a string')
    return done(warnings, errors)
  }

  if (!name.length) {
    errors.push('name length must be greater than zero')
  }
  // 不能以小数点开头
  if (name.match(/^\./)) {
    errors.push('name cannot start with a period')
  }
  // 不能以下划线开头
  if (name.match(/^_/)) {
    errors.push('name cannot start with an underscore')
  }
  // 不能在字符串开头或结尾有空格
  if (name.trim() !== name) {
    errors.push('name cannot contain leading or trailing spaces')
  }

  // 不能和黑名单的名字一致
  blacklist.forEach(function (blacklistedName) {
    if (name.toLowerCase() === blacklistedName) {
      errors.push(blacklistedName + ' is a blacklisted name')
    }
  })

  // Generate warnings for stuff that used to be allowed
  // 生成警告，之前npm允许的包名，但是现在不允许了
  
  // core module names like http, events, util, etc
  // 首先检验核心模块的包名
  builtins.forEach(function (builtin) {
    if (name.toLowerCase() === builtin) {
      warnings.push(builtin + ' is a core module name')
    }
  })

  // really-long-package-names-------------------------------such--length-----many---wow
  // the thisisareallyreallylongpackagenameitshouldpublishdowenowhavealimittothelengthofpackagenames-poch.
  // 长度检验
  if (name.length > 214) {
    warnings.push('name can no longer contain more than 214 characters')
  }

  // mIxeD CaSe nAMEs
  // 不能包含大写字母
  if (name.toLowerCase() !== name) {
    warnings.push('name can no longer contain capital letters')
  }
  // 不能包含特殊字符 `~)('!*`
  if (/[~'!()*]/.test(name.split('/').slice(-1)[0])) {
    warnings.push('name can no longer contain special characters ("~\'!()*")')
  }
  
  // 包名称不得包含任何非 url 安全字符（因为名称最终会成为 URL 的一部分）
  if (encodeURIComponent(name) !== name) {
    // Maybe it's a scoped package name, like @user/package
    var nameMatch = name.match(scopedPackagePattern)
    if (nameMatch) {
      var user = nameMatch[1]
      var pkg = nameMatch[2]
      if (encodeURIComponent(user) === user && encodeURIComponent(pkg) === pkg) {
        return done(warnings, errors)
      }
    }

    errors.push('name can only contain URL-friendly characters')
  }

  return done(warnings, errors)
}

包名称不得包含任何非 url 安全字符

因为发布的npm包在 www.npmjs.com 上都有一个页面，如果包含非 url 安全字符(?,=,/,&,)，比如包名为contain:colons的主页就是 https://www.npmjs.com/package/contain:colons 这个就会有问题。

encodeURIComponent 转义除了如下所示外的所有字符：
A-Z a-z 0-9 - _ . ! ~ * ' ( )

源码中首先判断 encodeURIComponent(name) !== name ，因为如果经过encodeURIComponent 转义之后有发生变化的字符串，那么说明这个字符串包含了非 url 安全字符，这个时候还得判断是否域包名(scoped package)，比如 @babel/plugin-proposal-export-namespace-from 就是一个域包名。

如果是一个域包名，那么除了一个@和一个/之外，不能再含有非 url 安全字符