package.json 生成
包名先校验,配置冲突当场报出来
如何使用本工具
- 选项目类型:库要发布、应用不发布、CLI 要生成可执行命令。
- 填包名和版本。包名会按 npm 的实际规则校验,大写的 A 也会被拦下来。
- 勾选项按需来,库默认开了 ESM、types、exports 和 files。
- 右侧实时生成 JSON,下方列出配置冲突——比如 CLI 没勾 bin 会直接报错。
- 确认无错误后复制或下载,放到项目根目录即可。
常见问题
Q:包名为什么必须小写?
A:npm 的包名会变成 URL 的一部分和文件系统目录名,大小写在不同操作系统上行为不一致。npm 从早期就强制小写,`MyTool` 会在 publish 时直接报错。作用域包也一样,`@Acme/tool` 不合法。
Q:`type: module` 一定要配 exports 吗?
A:不强制,但强烈建议。只写 main 时,CommonJS 的 `require()` 会拿到 ESM 文件然后报 ERR_REQUIRE_ESM。写了 exports 就能分别给 import 和 require 指不同文件。不过 Node 22 起支持 require ESM,老项目还是老老实实分开更稳。
Q:dependencies 和 devDependencies 怎么分?
A:运行时要用的放 dependencies,只在开发、构建、测试时用的放 devDependencies。判断标准很简单:把 node_modules 里 devDependencies 全删掉,应用还能不能跑?能跑就分对了。发布库时尤其要注意,把 TypeScript 或 eslint 误放进 dependencies 会让每个使用者都装一遍。
Q:private 和 UNLICENSED 有什么区别?
A:private: true 是 npm 层面的开关,阻止 `npm publish`;UNLICENSED 是许可证声明,告诉别人「不授权使用」。两者解决的问题不同,但内部项目通常两个都写。工具会在你只写 UNLICENSED 时提示加 private。
Q:bin 里的命令名怎么定的?
A:默认取包名斜杠后面的部分:`@acme/toolkit` → `toolkit`。这样安装后就能直接跑 `toolkit`。想换名字就得手动改 JSON,工具生成的是最常见的默认形式。
Q:engines 写 18 还是 >=18?
A:生成器输出 `>=18`。写死 `18` 会让 Node 20 用户也收到警告,这是错的。engines 是下限约束,不是精确版本。真要锁死版本用 `.nvmrc` 或 `volta`。
Q:semver 的预发布版本怎么写?
A:`1.0.0-beta.1`、`2.0.0-rc.3` 都合法,工具会放行。注意 `1.0` 不合法——npm 要求三段都写全。构建元数据用 `+`,比如 `1.0.0+build.5`,它不参与版本比较。