本参考补充 Lesson 0001 中关于 npm 包名的简要提及。VS Code 扩展也是 npm 包——发布扩展前必须遵守这些规则。
"全小写"是强制规则——npm registry 拒绝含大写字母的新包。
"短横线分隔"是社区约定——下划线_和点.在包名内部也合法。
| 规则 | 详情 |
|---|---|
| 全部小写 | 不允许任何大写字母（A-Z） |
| 最大 214 字符 | 含 scope 前缀（@scope/ 计入长度） |
不能以 . 或 _ 开头 | 例外：scoped 包允许（@scope/_name） |
| 不能有空格 | 任何位置都不允许 |
| 只能用 URL 安全字符 | ~'!*() 等特殊字符被禁止 |
| 不能用 Node.js 核心模块名 | http、stream、fs 等保留名称 |
| 包名 | 新包可用？ | 旧包可用？ | 原因 |
|---|---|---|---|
claude-context-bar | ✅ | ✅ | 完全合规 |
under_score | ✅ | ✅ | 下划线不在开头，合法 |
example.com | ✅ | ✅ | 点不在开头，合法 |
@scope/_hidden | ✅ | ✅ | Scoped 包可 _ 开头 |
MyPackage | ❌ | ✅ | 大写字母——新包禁止 |
_private_lib | ❌ | ✅ | 非 scoped 包不能 _ 开头 |
.hidden-pkg | ❌ | ✅ | 非 scoped 包不能 . 开头 |
my package | ❌ | ❌ | 空格在任何情况下非法 |
短横线 - 不能出现在 JavaScript 标识符中（它是减号运算符）。因此 npm 包名 my-package 和 JS 变量名 myPackage 永不冲突——天然命名空间分离。
如果包名叫 under_score，用户会困惑于 JS 中是写 under_score 还是 underScore。短横线消除了这种歧义。
VS Code 扩展发布时，publisher + name 共同构成唯一标识：
"publisher": "ezoosk" "name": "claude-context-bar" // Marketplace 上的唯一 ID：ezoosk.claude-context-bar
包名会同时出现在 npm registry 和 VS Code Marketplace 两条路径中。短横线命名在两个生态中都无摩擦。
npm 使用 validate-npm-package-name 校验所有包名。返回两个关键字段：
| 字段 | 含义 |
|---|---|
validForNewPackages | 你今天能发布这个名称吗？ |
validForOldPackages | 历史上是否曾经被允许？（遗留包可能还在用） |