如何为不发布到NPM的本地Node模块实现版本控制？

针对你需要的「无需发布NPM、独立版本控制、类NPM式导入」需求，这里提供两种可行方案，按需选择：

方案一：利用Node Subpath Imports（轻量配置，无需修改node_modules） #

1. 目录结构规划 #

先把内部模块按版本拆分独立目录，比如在项目外（或内部）创建存放内部模块的仓库：

your-workspace/
  main-project/          # 你的主项目
    package.json
    src/
  internal-modules/      # 内部模块仓库
    sample-module/
      1.0.0/
        package.json
        index.js         # 模块入口，导出someMethod
      1.0.1/
        package.json
        index.js
      1.0.2/
        package.json
        index.js

每个版本目录下的package.json需配置基础信息（以1.0.0为例）：

{
  "name": "sample-module",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js"
}

2. 主项目配置Subpath Imports #

在主项目的package.json中添加imports字段，将自定义模块路径映射到指定版本的模块文件：

{
  "name": "main-project",
  "type": "module",
  "imports": {
    "#sample-module": "../internal-modules/sample-module/1.0.2/index.js"
  }
}

3. 代码中导入 #

主项目代码里直接用映射后的路径导入：

import { someMethod } from '#sample-module'

版本切换 #

只需修改package.json中imports字段对应的版本路径即可，比如切换到1.0.0：

"imports": {
  "#sample-module": "../internal-modules/sample-module/1.0.0/index.js"
}

优缺点 #

• 优点：无需安装依赖、无node_modules软链接、配置简单
• 缺点：导入路径必须以#开头（Node Subpath规范强制要求），无法完全和NPM包导入路径一致

方案二：本地File协议安装（完全模拟NPM导入体验） #

1. 目录结构同方案一 #

保持内部模块按版本拆分的目录结构，每个版本有独立的package.json。

2. 本地安装指定版本模块 #

在主项目根目录执行命令，安装对应版本的本地模块：

npm install file:../internal-modules/sample-module/1.0.2

执行后，主项目package.json的dependencies会自动添加：

{
  "dependencies": {
    "sample-module": "file:../internal-modules/sample-module/1.0.2"
  }
}

3. 代码中导入 #

完全和NPM包一致的导入方式：

import { someMethod } from 'sample-module'

版本切换 #

• 方式一：重新安装目标版本

npm install file:../internal-modules/sample-module/1.0.0

• 方式二：手动修改package.json中sample-module的依赖路径，再执行npm install

优缺点 #

• 优点：导入路径完全和NPM包一致，符合你的预期；开发阶段修改版本目录代码会实时同步到主项目
• 缺点：每次切换版本需执行安装命令；node_modules中会生成对应版本的软链接

注意事项 #

• 所有模块需统一模块系统：如果用ES模块，务必在package.json中设置"type": "module"；如果用CommonJS，配置"main"字段即可
• 每个版本的模块需独立管理依赖，避免不同版本依赖冲突
• 若内部模块需要跨多个主项目复用，建议将internal-modules目录作为独立Git仓库管理，方便版本追踪

内容的提问来源于stack exchange，提问作者kzaiwo