企业官网建设流程全解析

• 开发工具
• CLI

n是 GitHub 加速计划 / n / n 仓库中的核心项目——一款用纯 Bash 编写的 Node.js 版本管理器，核心理念是"无子 shell、无 profile 配置、无繁琐 API，只有简单"。本指南以 README.md 为主线，结合仓库内 bin/n 源码、测试用例 与配套文档，完整讲解n的安装、版本指定、安装/移除、离线使用、镜像定制与底层工作原理，读完后你可以在 macOS、Linux 及 WSL 上直接用n接管 Node.js 多版本管理。

一、n是什么：设计理念与适用平台

n的目标是用最少的机制完成 Node.js 版本管理：不创建子 shell（对比 nvm 需要 source 进 profile），不修改你的 shell 初始化文件，只靠一个可执行文件完成下载、缓存、切换。仓库 package.json 中将其描述为 "Interactively Manage All Your Node Versions"，版本为 10.2.0，通过"bin": { "n": "bin/n" }暴露唯一的可执行入口。

支持平台方面，README 明确：

• 支持 macOS、Linux，包括 Windows Subsystem for Linux（WSL），以及其他各种类 Unix 系统；
• 虽然本身是 Bash 脚本（bin/n 首行为#!/usr/bin/env bash），但不要求你的交互 shell 是 Bash；
• 不工作于Microsoft Windows 原生 shell（如 PowerShell）、Git for Windows BASH，以及 Cygwin DLL 环境。

从 bin/n 源码可以看到其目录与镜像的默认设计：

VERSION="10.2.0" N_PREFIX="${N_PREFIX-/usr/local}" # 安装根目录，默认 /usr/local N_CACHE_PREFIX="${N_CACHE_PREFIX-${N_PREFIX}}" # 缓存根目录，默认等于 N_PREFIX CACHE_DIR="${N_CACHE_PREFIX}/n/versions" # 版本缓存目录 N_NODE_MIRROR=${N_NODE_MIRROR:-${NODE_MIRROR:-https://nodejs.org/dist}} # 发行版镜像 N_NODE_DOWNLOAD_MIRROR=${N_NODE_DOWNLOAD_MIRROR:-https://nodejs.org/download} # 下载区镜像 N_MAX_REMOTE_MATCHES=${N_MAX_REMOTE_MATCHES:-20} # ls-remote 默认最多列 20 个版本

即：缓存目录固定为n/versions子目录，而"当前激活"的 Node.js 被解压安装到bin、include、lib、share四个子目录中。

二、安装n：四种途径与权限处理

1. 通过 npm 安装（已有 Node.js 时）

npm install -g n

由于n默认安装根目录是/usr/local，普通用户通常没有写权限，可能遇到与npm install -g类似的权限报错。README 给出了三个可选方案：

1. 将相关目录的所有权改为当前用户（见下文）；
2. 通过N_PREFIX告诉n使用你有写权限的自定义位置（见"可选环境变量"一节）；
3. 在命令前加sudo以超级用户身份运行。

方案 1 的完整命令（README 原样保留）：

# make cache folder (if missing) and take ownership sudo mkdir -p /usr/local/n sudo chown -R $(whoami) /usr/local/n # make sure the required folders exist (safe to execute even if they already exist) sudo mkdir -p /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share # take ownership of Node.js install destination folders sudo chown -R $(whoami) /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share

2. 没有 npm 时的引导安装（curl 直跑）

如果还没有 Node.js，可以下载并直接运行n，先装一个 LTS 版本，再回头用 npm 安装n本身：

curl -fsSL https://raw.githubusercontent.com/tj/n/master/bin/n | bash -s install lts # If you want n installed, you can use npm now. npm install -g n

如果不需要n自身的更新能力，直接把脚本保存为可执行文件即可：

curl -fsSL -o /usr/local/bin/n https://raw.githubusercontent.com/tj/n/master/bin/n chmod 0755 /usr/local/bin/n n install lts

仓库 Makefile 也提供了等价的手工安装/卸载目标：make install（PREFIX默认为/usr/local，将bin/n拷贝到$(PREFIX)/bin/n）与make uninstall。

3. 第三方安装器

• macOS Homebrew：brew install n（formula 为 n）；
• macOS MacPorts：port install n；
• Linux/macOS 通用：n-install 脚本（curl -L https://bit.ly/n-install | bash）。它会同时设置PREFIX和N_PREFIX为$HOME/n，把n装到$HOME/n/bin，修改受支持 shell 的初始化文件以导出N_PREFIX并把$HOME/n/bin加入PATH，最后安装最新 LTS。这样n与其管理的所有 Node.js 版本都集中在单一目录，可用自带的n-uninstall脚本整体移除，n-update可更新n自身。

4. 替换旧的 Node.js 安装

从别的安装方式（如 Homebrew、系统包管理器、其他版本管理器）切换到n时，容易同时存在多份 node/npm/npx 甚至多份全局包。判断标准是安装输出中 "installed" 与 "active" 位置不一致：

% n lts copying : node/20.12.2 installed : v20.12.2 to /usr/local/bin/node active : v21.7.3 at /opt/homebrew/bin/node

两种解决思路（详见仓库文档 docs/changing-node-location.md）：

• 从旧目录卸载、再装到新目录（最直观，最终只保留一份 node）；
• 把n使用的bin目录放在PATH靠前位置，让n装的 node 被优先找到。

该文档以 Homebrew 为例给出了完整迁移演练：先brew list node与npm prefix --global确认旧前缀（如/opt/homebrew），npm list --global备份全局包清单；装好n并n lts后再用n doctor检查，此时会看到警告 "There is a version of node installed which will be found in PATH before the n installed version"；随后依次npm uninstall --global删除除 npm 外的全局包、卸载 npm、brew uninstall node，确认command -v node/npm/npx全部指向/usr/local/bin下的新安装，最后在新前缀下重装全局包。

三、安装 Node.js 版本：直接指定与交互菜单

最简单的用法是n <version>，未下载过则自动下载并安装，已下载则直接从缓存安装：

n 10.16.0 n lts

单独执行n（不带参数）会进入交互式选择界面，列出所有已下载版本，用方向键选择后回车安装：

$ n node/4.9.1 ο node/8.11.3 node/10.15.0 Use up/down arrow keys to select a version, return key to install, d to delete, q to quit

除了方向键，还支持j/k选择上一个/下一个，以及ctrl+n/ctrl+p。菜单模式下删除键d直接删除所选缓存版本，q退出。从源码看，bin/n 通过tput civis/smcup、stty -echo进入全屏菜单（enter_fullscreen），并用handle_sigint/handle_sigtstp妥善恢复终端（bin/n）。

如果安装后激活的 node 版本没有变化，可能是 shell 缓存了旧 PATH，打开新 shell 再验证。

四、版本指定方式全解析

n命令的版本参数支持多种形式，多数命令取"最新匹配"的版本，n ls-remote则会列出多个匹配版本。

数字版本（可完整可省略，可带前导 v）

• 4.9.1：精确版本；
• 8：匹配 8.x.y 系列；
• v6.1：匹配 6.1.x 系列。

源码中的校验正则印证了这一规则（bin/n）：is_numeric_version使用^[v]{0,1}[0-9]+(\.[0-9]+){0,2}$，而is_exact_numeric_version要求完整的^[v]{0,1}[0-9]+\.[0-9]+\.[0-9]+$。

特殊标签

• lts：最新的 Long Term Support 官方发布版；
• latest/current：最新的官方发布版。

auto 标签：从文件读取目标版本

auto会在当前目录或任意父目录按顺序查找以下版本文件：

1. .n-node-version：单行写版本号，n自有的约定；
2. .node-version：单行写版本号，被多个工具共用（node-version-usage）；
3. .nvmrc：单行写版本号，nvm 的约定；
4. 若以上文件都不存在，则回退到下面的engine解析逻辑。

测试用例 test/tests/version-resolve-auto-file.bats 系统验证了该行为：支持无结尾换行、Unix\n、Windows\r\n、前导v、只取首行，以及在子目录中向上查找父目录版本文件；.node-version中写4.9会被解析为4.9.1（部分版本号自动补全）。

engine 标签：从 package.json 读取

engine会查找package.json并读取engines字段确定兼容的 Node.js 版本。这要求系统已安装jq或node，遇到复杂版本范围（如>1、^18）时使用npx semver解析。对应测试 test/tests/version-resolve-auto-engine.bats 覆盖了8.9.0、v8.9.1、=8.9.2、=v8.9.3、>1（解析为最新版）等场景；源码中离线模式对此有限制：offline: an internet connection is required for looking up complex 'engine' ranges from package.json（bin/n）。

LTS 代号

argon、boron、carbon等 LTS 发布流的代号可以直接使用。源码is_lts_codename（bin/n）的完整匹配列表为 argon、boron、carbon、dubnium、erbium、fermium、gallium、hydrogen、iron、jod、krypton、lithium（不区分大小写）。

Node.js 支持别名

active、lts_active、lts_latest、lts、current、supported可用，但都会被解析为对应的最新匹配版本。源码display_latest_node_support_alias（bin/n）展示了映射关系：active/supported→current，lts_active/lts_latest/lts→lts；is_node_support_version（bin/n）负责识别这类别名。

其他发布流（下载文件夹形式）

最后一种形式是直接使用远程下载文件夹名（对应 nodejs.org/download 下的目录），可跟完整或不完整版本号：

• nightly
• test/v11.0.0-test20180528
• rc/10

源码is_download_folder（bin/n）识别的文件夹为next-nightly|nightly|rc|release|test|v8-canary，is_download_version（bin/n）负责文件夹/版本形式，update_mirror_settings_for_version（bin/n）会据此把镜像 URL 切换到N_NODE_DOWNLOAD_MIRROR/<folder>。

五、移除与清理版本

# 删除若干缓存版本（可同时指定多个） n rm 0.9.4 v0.10.0 # 删除除当前安装版本外的全部缓存版本 n prune # 卸载已安装的 Node.js（不影响缓存版本） n uninstall

n uninstall的适用场景包括：回退到系统自带的 node（如果它在另一个位置）、不再需要 node/npm，或打算改用其他版本管理方式。

六、不重装直接使用下载版本：which / run / exec

n提供三个直接操作已下载版本的命令（无需重新安装）：

# 显示某个已下载 node 的完整路径 $ n which 6.14.3 /usr/local/n/versions/6.14.3/bin/node # 用指定版本运行脚本（可附加参数） n run 8.11.3 --debug some.js # 以修改后的 PATH 执行命令，使 node 和 npm 来自指定版本 n exec 10 my-script --fast test n exec lts zsh

注意：通过n exec运行的npm会使用目标 node 版本目录下的全局 node_modules。默认情况下，如果目标版本尚未缓存，run/exec/which会直接失败；加上--download则"有缓存用缓存、无缓存就下载"：

n --download run 18.3 my-script.js

七、保留 npm：--preserve 与相关环境变量

Node.js 安装包通常自带npm、npx和corepack。如果你希望保留当前（尤其是更新版本）的 npm，可以使用--preserve（即-p）：

$ npm install -g npm@latest ... $ npm --version 6.13.7 # Node.js 8.17.0 includes (older) npm 6.13.4 $ n -p 8 installed : v8.17.0 $ npm --version 6.13.7

也可以设置环境变量使其成为默认行为（npm 与 corepack 分开控制）：

export N_PRESERVE_NPM=1 export N_PRESERVE_COREPACK=1

还可以显式指定以覆盖环境变量：

n --preserve nightly n --no-preserve latest

源码层面，bin/n 的安装复制逻辑正是围绕这一开关设计的：未设置N_PRESERVE_NPM时才从缓存拷贝npm/npx及lib/node_modules/npm，未设置N_PRESERVE_COREPACK时才拷贝corepack；命令行解析处-p|--preserve会同时置位两个变量（bin/n）。

八、常用命令速查

--cleanup的典型场景是容器内一次性安装，README 示例：

curl -fsSL https://raw.githubusercontent.com/tj/n/master/bin/n | bash -s install --cleanup lts

此外，bin/n 的--help输出还给出了命令别名：install: i、latest: current、ls: list、lsr: ls-remote、lts: stable、rm: -、run: use, as、which: bin。

九、自定义镜像与架构

自定义镜像（N_NODE_MIRROR）

默认镜像为https://nodejs.org/dist/，如果需要同布局的镜像，可设置N_NODE_MIRROR。README 给出的典型示例：

# 中国大陆用户常用镜像 export N_NODE_MIRROR=https://npmmirror.com/mirrors/node # Node.js unofficial-builds 项目，提供 armv6l（树莓派）、32 位 x86 等官方未覆盖平台 export N_NODE_MIRROR=https://unofficial-builds.nodejs.org/download/release

使用 unofficial-builds 时，如果系统架构无法被自动探测（如 Alpine 上的musllibc），需要显式指定架构：

export N_NODE_MIRROR=https://unofficial-builds.nodejs.org/download/release export N_ARCH=x64-musl apk add bash curl libstdc++ n install lts

镜像需要认证时，可以把 URL-encoded 的用户名密码写进 URL：

export N_NODE_MIRROR=https://encoded-username:encoded-password@host:port/path

另有N_NODE_DOWNLOAD_MIRROR用于指定与https://nodejs.org/download同布局的下载区镜像（nightly、rc 等发布流会用到，见 bin/n 与update_mirror_settings_for_version）。

自定义架构（--arch / N_ARCH）

默认n选择与系统架构匹配的二进制（如 64 位系统下载 64 位包）。在 Apple silicon（M 系列）Mac 上：

• Node.js 16 及以上：默认 arm64 原生二进制；
• 更老版本：默认 x64 二进制，通过 Rosetta 2 运行。

这一逻辑由update_arch_settings_for_version（bin/n）实现：当平台是darwin-arm64且主版本号小于 16 时，自动回退ARCH=x64。可用-a/--arch或环境变量N_ARCH覆盖，例如重装最新版的 x64 二进制：

n rm current n --arch x64 current

十、可选环境变量一览

# 安装根目录（默认 /usr/local），例如放到用户目录： export N_PREFIX=$HOME/.n export PATH=$N_PREFIX/bin:$PATH # 仅改变下载缓存位置（不影响激活版本的安装位置）： export N_CACHE_PREFIX=... # xz 压缩包开关（默认自动探测系统 tar 是否支持 xz）： export N_USE_XZ=0 # 禁用 export N_USE_XZ=1 # 启用

对应的命令行显式开关：

n install --use-xz nightly n install --no-use-xz latest

完整变量清单（README "In brief" 部分）：

• N_NODE_MIRROR：见"自定义镜像"；
• N_NODE_DOWNLOAD_MIRROR：见"自定义镜像"；
• NO_COLOR与CLICOLOR=0：控制是否输出 ANSI 颜色码。源码中的判定逻辑为（bin/n）：CLICOLOR_FORCE非零强制启用；否则NO_COLOR已定义、CLICOLOR=0或输出非终端（! -t 1）时禁用；
• N_MAX_REMOTE_MATCHES：修改ls-remote默认最多 20 个匹配版本的上限；
• N_PRESERVE_NPM：见"保留 npm"；
• N_PRESERVE_COREPACK：见"保留 npm"；
• N_ARCH：见"自定义架构"。

此外源码还保留了未在 README 中记录的旧式兼容变量HTTP_USER/HTTP_PASSWORD（bin/n），二者必须成对出现，否则会abort。

十一、工作原理：单前缀覆盖 + 缓存复用

n的工作方式非常朴素：

1. 下载官方预编译 Node.js 包（底层使用curl，不可用时退回wget；CURL_OPTIONS默认含--location --fail --show-error，见 bin/n）；
2. 解压并安装到单一前缀目录（如/usr/local），直接覆盖上一个版本；该位置的bin目录（如/usr/local/bin）应在你的PATH中；
3. 下载的压缩包保留在缓存目录（$N_CACHE_PREFIX/n/versions），用于重复安装，也可通过n which/n run/n exec有限使用；
4. 安装不会改动你的全局 npm 包，唯一例外是 npm 本身——它是 Node.js 安装包的一部分，会被对应版本覆盖。

从安装复制逻辑（bin/n）还可以看到若干实现细节：先复制lib再复制bin（保证符号链接目标存在）；复制lib时跳过node_modules（避免混入已装的全局模块）；bin下逐项复制node、npm、npx、corepack，并按--preserve开关决定是否跳过；share目录单独处理man（某些 Linux 发行版如 Arch 上它是符号链接）。

十二、疑难诊断与扩展阅读

• 版本不生效：安装后 "installed" 与 "active" 不一致，多半是PATH中其他位置的 node 排在前面。运行n doctor检查 PATH 优先级、目录权限与镜像可达性（源码见 bin/n 的show_diagnostics），或在PATH中把$N_PREFIX/bin提前。
• 代理环境：n的下载依赖curl/wget，走代理时设置https_proxy（HTTP 镜像则用http_proxy），sudo下记得sudo -E n lts保留环境变量；证书不被信任时可加--insecure。完整方案（含~/.curlrc、~/.wgetrc配置与排查示例）见仓库文档 docs/proxy-server.md。
• 离线环境：用n download <version>在有网机器上预下载，再用n --offline 12在无网环境从缓存解析安装；相关行为由 test/tests/offline.bats 覆盖。
• 从其他方式迁移：参考 docs/changing-node-location.md 中 Homebrew →n的完整切换演练（含n doctor警告解读与全局包迁移）。

结语

n以"下载预编译包 + 单前缀覆盖安装 + 目录缓存"的最小模型，实现了不依赖子 shell 与 profile 配置的 Node.js 版本管理。从安装、交互菜单、auto/engine版本解析，到镜像/架构定制与离线使用，本文覆盖了 README.md 的全部核心内容，并结合 bin/n 源码与 测试用例 给出了实现级印证。无论你是想替换 Homebrew 管理 Node.js，还是需要在 CI/Docker 中做一次性安装，n都值得放进工具链。

• 开发工具
• CLI