xyh-n

xyh-n 是一个面向 Windows x64 的离线 Node.js 版本管理工具，命令名为 cib-n。

它适合在内网、离线环境或无法直接访问 Node.js 官方下载源的机器上使用。你可以提前把 Windows x64 的 Node.js zip 包放进项目的 versions/ 目录，安装后通过 cib-n 快速切换本机使用的 Node.js 版本。

功能

• 离线管理多个 Windows x64 Node.js 版本
• 支持导入本地 Node.js zip 包
• 支持交互选择、查看、切换、卸载、清理已导入版本
• 显示 shell 实际运行的 Node.js 版本
• 自动配置 Windows 用户级 PATH，也支持系统级 PATH
• 提供当前终端 PATH 刷新命令

环境要求

• Windows x64
• Node.js >= 14.0.0
• PowerShell 可用

当前工具只支持 Windows x64 的 Node.js zip 包，文件名必须符合以下格式：

node-v18.20.4-win-x64.zip

安装

从 npm 或内部 npm 仓库安装：

npm install -g xyh-n

安装后会得到 cib-n 命令，并显示首次使用引导：

cib-n --help
cib-n doctor

准备离线 Node.js 包

从有网络的机器下载 Windows x64 版本的 Node.js zip 包，例如：

node-v18.20.4-win-x64.zip
node-v20.19.0-win-x64.zip

然后可以通过以下方式导入：

cib-n import ./node-v18.20.4-win-x64.zip

如果你要发布带有内置 Node.js 版本的安装包，也可以在发布前把 zip 包放入项目的 versions/ 目录：

versions/node-v18.20.4-win-x64.zip
versions/node-v20.19.0-win-x64.zip

常用命令

交互选择版本：

cib-n

运行后可以使用 Up/Down 选择版本，按 Enter 切换，按 q 或 Esc 取消。

查看已导入版本：

cib-n ls

或：

cib-n list

切换到指定版本：

cib-n 18.20.4

等价于：

cib-n use 18.20.4

切换到已导入的最新版本：

cib-n latest

查看当前选中版本和 shell 实际版本：

cib-n current

或：

cib-n which

诊断 PATH 和版本是否一致：

cib-n doctor

卸载某个版本：

cib-n rm 16.20.2

或：

cib-n uninstall 16.20.2

刷新当前终端 PATH：

Invoke-Expression (cib-n env powershell | Out-String)

配置 PATH：

cib-n setup

默认写入当前用户的 PATH。如果需要写入系统 PATH，请以管理员身份运行：

cib-n setup --system

清理解压后的版本目录：

cib-n clean

clean 只会删除 versions/ 下已经解压的 Node.js 目录，不会删除原始 zip 包。再次切换到对应版本时会自动重新解压。

工作方式

cib-n 会把导入的 zip 包复制到工具安装目录下的 versions/ 目录。第一次切换到某个版本时，会自动解压该 zip 包，并把安装目录下的 current 链接指向对应 Node.js 目录。

切换成功后，cib-n 会确保 current 在 PATH 中。之后终端里执行的 node、npm、npx 会来自当前选择的 Node.js 版本。

如果 cib-n current 显示的选中版本和 shell 实际版本不一致，执行：

Invoke-Expression (cib-n env powershell | Out-String)

然后再验证：

node -v
npm -v

如果刚配置过 PATH，也可以重新打开终端后再验证。

打包发布

发布前请确认 versions/ 目录存在。项目已配置 prepack 脚本，会在打包前自动创建该目录。

本地打包：

npm pack

发布到 npm 或内部 npm 仓库：

npm publish

如果需要让安装包自带 Node.js 版本，请在执行 npm pack 或 npm publish 前，把对应 zip 包放入 versions/ 目录。

版本与发版

本项目使用 Changesets 管理版本和 CHANGELOG.md。Changesets 不会自动 git commit，需要按下面流程手动提交。

推荐流程

1. 开发功能 / 修复 bug
2. npm run changeset          → 生成 .changeset/xxx.md
3. git add . && git commit      → 与功能代码一起提交并 push
4. 合并到 main
5. npm run version-packages   → 更新 package.json 和 CHANGELOG.md
6. git add . && git commit      → 提交发版变更（如 chore: release v1.3.0）
7. git tag v1.3.0 && git push --tags
8. npm run release            → 发布到公司 npm 私服

各步骤说明

开发阶段：记录变更

npm run changeset

按提示选择 patch / minor / major，并填写变更摘要。摘要会原样写入 CHANGELOG，建议直接用中文填写，例如：

新增 doctor 命令，支持诊断 PATH 与 Node 版本不一致问题

然后提交：

git add .changeset/ bin/ README.md
git commit -m "feat: 新增 doctor 命令"
git push

发版阶段：更新版本号

功能合并到 main 后执行：

npm run version-packages

这会：

• 读取 .changeset/ 下未消费的 changeset 文件
• 更新 package.json 版本号
• 更新 CHANGELOG.md
• 删除已消费的 .changeset/*.md

然后手动提交发版结果：

git add package.json CHANGELOG.md
git commit -m "chore: release v1.3.0"
git push
git tag v1.3.0
git push origin v1.3.0

发布到公司私服

npm run release

或先本地验证安装包：

npm pack
npm install -g ./xyh-n-1.3.0.tgz

.changeset 目录要不要提交？

要提交，规则如下：

| 文件 | 是否提交 | 说明 | |------|----------|------| | .changeset/config.json | 是 | 发版配置，始终在仓库里 | | .changeset/xxx.md | 是 | 开发完成后生成，和功能代码一起提交 | | 已消费的 .changeset/xxx.md | 否 | version-packages 后会自动删除 |

.changeset/xxx.md 相当于“待发版清单”，不提交的话其他人无法汇总版本变更。

发版类型

• patch：bug 修复
• minor：新增命令或非破坏性功能
• major：破坏性变更

更新内置 Node.js zip 包时，也应在 changeset 摘要里说明，即使 CLI 代码没有改动。

本地测试安装包

npm pack
npm install -g ./xyh-n-1.3.0.tgz
cib-n doctor

测试完卸载：

npm uninstall -g xyh-n

注意事项

• 只支持 win-x64 zip 包，不支持 exe/msi 安装包。
• zip 包文件名必须是 node-v{version}-win-x64.zip。
• 修改系统 PATH 需要管理员权限。
• 非 Windows 系统不会自动写入 PATH，只会提示需要手动添加的路径。