npm 项目命名规则

以下是 npm 项目命名规则的详细说明：

一、核心命名规则

1. 必须使用小写字母

   • 名称中不能包含大写字母。
   • 原因：
     • 跨平台兼容性（如 Linux 区分大小写，而 Windows 不区分）。
     • 避免命令行和 URL 中的大小写冲突（例如包名会出现在 npm 网址或命令中）。
     • 统一社区规范，减少命名冲突。

2. 允许的字符

   • 可以包含小写字母、数字和连字符（-）。
   • 禁止：
     • 空格、下划线（_）、点（.）或其他特殊字符。
     • 不能以连字符（-）开头或结尾。

3. 长度限制

   • 名称长度必须在 1 到 214 个字符 之间。

4. 唯一性

   • 名称必须全局唯一，不能与已存在的 npm 包名冲突。
   • 检查方法：
     • 使用 npm view <name> 命令或访问 npm 官网 搜索包名。

5. 保留字限制

   • 不能使用 npm 保留的关键字（如 npm、test 等）。

二、作用域命名（Scope）

1. 作用域格式

   • 使用 @scope/package-name 的形式，例如 @myorg/mypackage。
   • 作用：
     • 避免与他人包名冲突。
     • 组织或团队可统一管理相关包。

2. 作用域包的发布

   • 默认为私有包，需在 package.json 中配置 publishConfig 为公开：

     "publishConfig": {
       "access": "public",
       "registry": "https://registry.npmjs.org/"
     }
     

三、命名规范建议

1. 命名风格

   • 使用连字符分隔单词，例如 google-map-react 而非 GoogleMapReact。
   • 避免使用下划线（_）或驼峰命名（camelCase）。

2. 避免歧义

   • 确保名称语义清晰，能明确表达包的功能。
   • 避免与现有知名包名过于相似（如 react-native 已存在，则 react.native 会被拒绝）。

3. 检查名称可用性

   • 在 package.json 中填写名称前，务必通过 npm view <name> 或官网确认未被占用。

四、常见错误示例

1. 错误命名

   # 包含大写字母
   npx create-react-app GoogleMapReact 
   # 错误提示：Cannot create a project named "GoogleMapReact" because of npm naming restrictions
   

2. 正确命名

   # 使用小写和连字符
   npx create-react-app google-map-react
   

五、其他注意事项

1. 版本号规范

   • 遵循语义化版本（SemVer）：MAJOR.MINOR.PATCH，例如 1.0.0。
   • 预发布版本可添加后缀（如 1.0.0-beta.1）。

2. package.json 必填字段

   • name 和 version 是必填项，且需符合上述规则。

3. 发布到 npm

   • 如果名称包含作用域（如 @scope/xxx），需先在 npm 注册作用域（组织或用户）。

六、总结

• 核心原则：小写、连字符分隔、唯一且符合 URL 安全规范。
• 作用域命名：适合团队协作或避免名称冲突。
• 检查工具：npm view、npm 官网搜索。

通过遵循这些规则，可以确保项目名称符合 npm 的规范，避免兼容性问题，并提升包的可维护性和可发现性。