POT规范｜一套个人自研NPM包本地生命周期管理体系

前言

很多前端开发者都会自己写一些NPM工具包，但是大部分人只关注包内部代码，很少去思考：手上十几个、几十个自研NPM包，在本地电脑上如何统一管理、区分不同状态。

市面上大量教程都在讲解monorepo、changesets、打包构建、单个包的目录结构。但对于个人开发者来说，重型工具上手成本高，很多时候只是需要一套简单清晰的本地工作流，用来区分：正在开发的包、已经发布稳定的包、线上包的验证Demo。

基于这个痛点，我总结出一套轻量的本地NPM包管理方案，命名为POT规范。 POT取自三个核心目录首字母：Preparation、Ok、Test。 这套规范不依赖复杂工具，核心就是按包生命周期划分三层本地目录，适合个人开发者维护自制NPM包。

大家也可以先去看看百科了解一下：

POT 规范 - 百度百科

一、POT规范整体目录结构

在本地建立一个总根目录，下面固定3个顶层文件夹：

npm-packages-root/ ├── npm_preparation # P - Preparation 草稿&开发区 ├── npm_ok # O - Ok 稳定归档区 └── npm_test # T - Test 线上包验证Demo区

重要约定：版本信息唯一数据源为包内package.json，不会在文件夹名称手动标注版本号，避免两处版本信息不一致引发人为错误。

二、三大目录职责详解

1. npm_preparation（Preparation｜草稿 & 开发准备区）

这是包的开发起点。所有新包开发、已有包迭代，都放在这里。

• 用于包的前期构思、代码编写、原型迭代；
• 代码编写完成后，优先使用npm link做本地源码联调测试；
• npm link直接关联本地源码，不需要发布到NPM，方便开发阶段快速调试；
• 本地link测试全部通过后，执行npm publish发布到NPM仓库；
• 发布成功之后，才将包源码迁移至npm_ok归档。

2. npm_ok（Ok｜已发布稳定归档区）

存放已经发布到NPM、验证通过的包源码，相当于稳定快照目录。 ✅ 核心规则：

• 进入该目录的包，代表线上已发布，是经过验证的可用稳定版本；
• 普通迭代，禁止直接在npm_ok内修改源码。 如果需要新增功能、轻微优化，复制npm_ok中的稳定包源码到npm_preparation进行新版本开发；npm_ok保留旧稳定版本，不会被半成品污染。新版本发布完成后，再更新归档。

⚠️ 特殊场景：线上严重Bug 发现重大线上bug，优先通知包使用者。修复开发阶段，先不往npm_ok存放，等到修复、测试、重新发布全部确认无误后，再归档。

3. npm_test（Test｜线上包Demo回归测试区）

重点：这个目录不存放包源码，只存放独立的测试Demo项目。

• 不再使用npm link，完全模拟真实用户行为：通过npm install从线上NPM仓库拉取已发布的包；
• 编写Demo代码，验证打包后的发布产物是否正常可用；
• 核心价值：隔离两套测试。npm link测源码，npm_test测线上打包产物，很多打包、导出、文件缺失类问题，只有真实安装包才会暴露；
• 同时承接用户Issue回归：收到用户反馈bug，可以在这里新建Demo复现问题，完成回归验证。

三、POT规范完整工作流转

1. 开发阶段：在npm_preparation编写包源码
2. 本地源码调试：使用npm link进行本地联调，验证功能
3. 本地link测试全部通过 → 执行npm publish发布包
4. 发布成功 → 将包源码迁移至npm_ok做稳定归档
5. 线上产物验证：进入npm_test新建Demo项目，npm install线上包做最终验收
6. 后续迭代分两种场景处理：
   • ✅ 普通迭代（新增功能、小优化）：复制npm_ok稳定包到npm_preparation开发新版本；旧版本继续保存在npm_ok，新版本发布完成后再归档。
   • ⚠️ 严重线上Bug：提前告知使用者，修复开发期间不归档到npm_ok，全部验证发布完成后再归档。

四、POT规范的优势

1. 状态直观：打开本地文件夹，一眼区分包状态：草稿开发 / 已上线稳定 / 线上包测试Demo，不用打开NPM官网、Git仓库查询状态。
2. 轻量低成本：不需要pnpm monorepo、changesets这类重型工具，个人开发者开箱即用，渐进落地。
3. 测试环境隔离：源码link调试 + 线上包安装测试两套环境，覆盖不同场景，降低发布踩坑概率。
4. 单一版本数据源：版本号统一维护在package.json，不手动修改文件夹命名，规避人为错误。
5. 方便Bug回归：所有Issue对应的复现Demo统一放在npm_test，方便后续回溯查看。

五、配套补充注意事项

1. 废弃包处理：在npm_ok内部新建子目录deprecated存放废弃包源码，同时在NPM官方使用npm deprecate标记废弃提示，引导用户迁移。
2. 包之间互相依赖：开发阶段在npm_preparation通过npm link调试包依赖关系；上线验证放到npm_test，使用正式安装方式测试。
3. 备份建议：npm_ok存放稳定归档源码，建议定期备份。

== 适用场景 ==
POT规范适用于个人前端开发者维护自制npm工具包、组件库，用于规范本地包生命周期，隔离开发、归档、测试目录，减少版本混乱。

== 约束要点 ==
POT规范核心约束：禁止直接修改npm_ok目录内已发布包的源码快照；所有功能迭代、代码修改，均需要在npm_preparation目录中完成开发。

结尾

市面上很多工程方案都偏向团队大型项目，而POT规范面向个人开发者，解决的是本地大量自研NPM包的生命周期收纳管理。 POT规范不是用来替代Git，它只是一套本地电脑的工作流约定，用简单的目录划分，让我们自己写的NPM包，从构思、开发、发布、归档到bug回归，整个流程清晰可控。

互动提问：你平时维护多个NPM包的时候，本地代码是怎么存放的？欢迎评论区交流。