Node.js

mise installs Node.js from the official nodejs.org builds and selects a version per project. It can also read .nvmrc, .node-version and package.json, so projects set up for other version managers keep working.

Quick start

Select Node.js for the current project and check it without depending on shell activation:

mise use node@26
mise exec -- node --version

mise use writes node = "26" to mise.toml. Use mise use -g node@26 for a personal default; a project's version overrides it inside that project. mise upgrade node updates within the configured request.

nodejs is an alias for node; see the FAQ. For project recipes, see the Node.js cookbook.

Choosing a version

Request	Selects
node@26	The newest 26.x release
[email protected]	That release
node@lts	The newest release of the current LTS line
node@lts/krypton	The newest release of a named LTS line (lts-krypton also works)
node@latest	The newest release

List the available versions with mise ls-remote node, or one release line with mise ls-remote node 26. See version requests for the full syntax.

Version files

mise does not read .nvmrc, .node-version or package.json until you enable them for Node.js:

mise settings add idiomatic_version_file_enable_tools node

This changes your global config. Add --local to enable it in the project's mise.toml instead, so teammates get the same behavior. See idiomatic version files.

.nvmrc aliases such as lts/* and lts/iron work as they do in nvm, and a leading v is ignored. To read .nvmrc and .node-version but not package.json:

mise settings add idiomatic_version_file_disable_files node:package.json

package.json

mise reads devEngines.runtime when its name is node:

package.json

{
  "devEngines": {
    "runtime": { "name": "node", "version": "26.10.0" }
  }
}

This selects Node.js 26.10.0. devEngines.runtime can be an object or an array; mise reads the first entry of an array. See the Bun and Deno pages for other runtimes.

mise does not read engines.node, which describes the Node.js versions a package is compatible with, not the version to develop with. If a project only has an engines range, select a version explicitly:

mise use node@24

Package managers

npm ships with Node.js. mise can also install and select npm, pnpm and Yarn as separate tools, without Corepack, and aube, which works with existing npm, pnpm and Yarn lockfiles. See the Node.js cookbook for project recipes with pnpm and aube.

Pin the npm version

To keep a team on the same npm, and avoid package-lock.json churn between npm versions, pin npm next to Node.js:

mise.toml

[tools]
node = "26"
npm = "11"

To write exact versions for both:

mise use --pin node@lts npm@latest

This writes the resolved versions to mise.toml. Inside the mise environment, the separately configured npm takes precedence over the npm bundled with Node.js; check it with mise exec -- npm --version. This selects the npm executable; the project's lockfile still controls its dependencies.

package.json 中的软件包管理器版本

mise can read the npm, pnpm or Yarn version from package.json. Enable each package manager that a repository may declare:

mise.toml

[settings]
idiomatic_version_file_enable_tools = ["npm", "pnpm", "yarn"]

mise reads a matching devEngines.packageManager declaration first, then the top-level packageManager field. The declaration's name must match the enabled tool:

package.json

{
  "packageManager": "[email protected]"
}

This selects pnpm 10.15.0. The equivalent devEngines declaration is:

package.json

{
  "devEngines": {
    "packageManager": { "name": "pnpm", "version": "10.15.0" }
  }
}

devEngines.packageManager can also be an array; mise reads its first entry. For Bun's runtime and package-manager precedence, see Bun version files.

A Corepack-style checksum suffix (+sha1, +sha224, +sha256, +sha384 or +sha512) is verified against the exact package-manager artifact before installation:

package.json

{
  "packageManager": "[email protected]+sha224.88208eb7c2e7de6ed534fa298248dee656723116995eda4b508fd0c9"
}

For npm, pnpm and Yarn 1, that artifact is the npm registry tarball. For Yarn 2 and later it is Yarn's published CLI file, and the declaration must name an exact Yarn version. Without a checksum, mise installs the package manager through its usual registry backend and that backend's verification.

Unlike Corepack, mise does not pick a known-good package-manager version when a project declares none. Set the version in mise.toml, package.json or your global config.

Corepack

mise installs package managers itself, so Corepack is not needed. If you still want Corepack's shims, set node.corepack to true; mise then runs corepack enable after installing any Node.js version that includes Corepack.

Global npm packages

npm install -g installs into the active Node.js version, unless your .npmrc sets a different prefix. A globally installed command is therefore not available after you switch Node.js versions.

On macOS and Linux, mise replaces each version's bin/npm with a small wrapper that runs mise reshim after global installs and uninstalls, so new commands get shims. Turn it off with node.npm_shim.

To keep a CLI across Node.js versions, install it as its own tool with the npm backend, for example mise use -g npm:typescript.

How mise installs Node.js

mise downloads the official binary archive for your platform from node.mirror_url (https://nodejs.org/dist/ by default), checks it against the release's SHASUMS256.txt, and verifies the OpenPGP signature on that file when the release publishes one (node.gpg_verify). It then runs node -v and npm -v. mise sets no Node.js-specific environment variables; the version's bin directory goes on PATH.

When no binary exists for your platform, mise compiles Node.js from source, unless node.compile is false.

On Alpine and NixOS, mise currently compiles from source by default, because all_compile defaults to true there. This default is deprecated, and mise 2027.8.0 switches to precompiled binaries. To use precompiled binaries now, set node.compile = false or all_compile = false; on NixOS, enable nix-ld first. To keep compiling, set all_compile = true explicitly.

An installed plugin named node takes precedence over the built-in installer. If mise behaves differently from this page, check mise plugins ls and see selecting another implementation.

Compiling from source

Set node.compile to build Node.js instead of downloading a binary. Install Node.js's build dependencies first:

mise settings node.compile=true
mise install node@26

mise uses ninja when it is on PATH. The node.ninja, node.concurrency, node.configure_opts, node.cflags and node.apply_patches settings tune the build.

Unofficial builds

The unofficial builds project publishes Node.js for platforms the official builds do not cover.

On musl hosts such as Alpine, mise detects musl and, when it downloads a binary rather than compiling (see the Alpine note above), fetches Node.js's musl flavor from the unofficial builds automatically while node.mirror_url is the default. The libc setting set to musl has the same effect.

For other platforms, such as linux-loong64 or linux-armv6l, or for the glibc-217 flavor built against an older glibc, point mise at the unofficial builds:

mise settings node.mirror_url=https://unofficial-builds.nodejs.org/download/release/

Then choose a flavor with node.flavor if you need one:

mise settings node.flavor=glibc-217

Migrating from nvm, nodenv, or Homebrew

To reuse Node.js versions you already installed, link them into mise with mise sync node:

mise sync node --nvm     # reads versions under node.nvm_dir (NVM_DIR)
mise sync node --nodenv  # reads versions under node.nodenv_root (NODENV_ROOT)
mise sync node --brew    # reads Homebrew's versioned node@NN formulae

mise sync does not overwrite versions mise installed itself. Then enable .nvmrc and .node-version as described in Version files.

Tool options

Node.js has no Node.js-specific options. install_env reaches source builds, the node -v and npm -v checks, default package installs, corepack enable and postinstall commands. For example, to override compiler flags for a source build:

mise.toml

[tools]
node = { version = "26", install_env = { CFLAGS = "-O2" } }

Other generic options are described in tool options.

Default packages file deprecated

mise installs the packages listed in ~/.default-npm-packages (node.default_packages_file), one per line, with npm install --global into each new Node.js version. mise warns about this file from 2026.11.0 and stops reading it in 2027.11.0. Install npm CLIs with the npm backend instead, for example "npm:typescript" = "latest", or use a postinstall command for packages every Node.js version needs.

设置

请在配置文件的 [settings] 下设置这些值，或使用 mise settings set，也可以使用设置对应的环境变量。 请参阅哪个值生效，了解同一设置在多个位置配置时的优先级。

node.apply_patches

Patch files or URLs to apply to the Node.js source before building it.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_APPLY_PATCHES

List one patch file or URL per line. mise applies them to the extracted source before ./configure runs. They apply only to source builds: with node.compile = true, or when no precompiled build exists for the version and mise compiles instead. When mise installs a precompiled build, it warns that the patches were skipped.

node.cflags

Extra CFLAGS for compiling Node.js, for example to replace -O3.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_CFLAGS

When unset, mise uses NODE_CFLAGS from the environment.

node.compile

Compile Node.js from source instead of using a precompiled build.

• 类型：布尔值
• 默认值：未设置
• 环境变量：MISE_NODE_COMPILE

false uses only precompiled builds and fails when none exists. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one exists and compiles otherwise. See Building from source.

node.concurrency

Number of parallel jobs (make -j) when compiling Node.js.

• 类型：整数
• 默认值：physical CPU cores, or unset when node.ninja is on
• 环境变量：MISE_NODE_CONCURRENCY

Values below 1 count as 1. With node.ninja, ninja picks the job count when this is unset.

node.configure_opts

Extra arguments for ./configure when compiling Node.js.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_CONFIGURE_OPTS

When unset, mise uses NODE_CONFIGURE_OPTS from the environment.

node.corepack

Run corepack enable after installing a Node.js version, so yarn and pnpm go through Corepack.

• 类型：布尔值
• 默认值：false
• 环境变量：MISE_NODE_COREPACK

Applies to Node.js versions that include Corepack. When node.npm_shim is off, mise also runs corepack enable npm. mise installs package managers itself, so Corepack is optional; see Corepack.

node.default_packages_file已弃用

File listing npm packages to install globally into each new Node.js version.

• 类型：路径
• 默认值："~/.default-npm-packages"
• 环境变量：MISE_NODE_DEFAULT_PACKAGES_FILE
• 已弃用：Default npm package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every node version, or use the npm: backend for CLI tools.

One package per line, with an optional version:

typescript@latest
@types/node@^24

When this is unset, mise uses NODE_DEFAULT_PACKAGES_FILE, then ~/.default-nodejs-packages or ~/.default-node-packages if one exists, and otherwise ~/.default-npm-packages. See Default packages file.

node.flavor

Linux build flavor of Node.js to download, such as musl or glibc-217.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_FLAVOR

Flavors come from the unofficial builds project, so also set node.mirror_url to https://unofficial-builds.nodejs.org/download/release/. musl is the exception: with the default mirror, mise downloads it from the unofficial builds by itself, and it selects musl automatically on musl hosts. See Unofficial builds.

node.gpg_verify

Check the OpenPGP signature of the SHASUMS256.txt file that node.verify checks downloads against.

• 类型：布尔值
• 默认值：true
• 环境变量：MISE_NODE_GPG_VERIFY

mise checks the signature itself, so gpg does not need to be installed. It runs only when node.verify is on, and skips releases that never published a signature (the .sig download returns 404). Set to false to skip the check. The global gpg_verify setting sets the default.

node.make

Command to run instead of make when compiling Node.js, such as gmake.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_MAKE

Used for both the build and make install.

node.make_install_opts

Extra arguments for make install when compiling Node.js.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_MAKE_INSTALL_OPTS

When unset, mise uses NODE_MAKE_INSTALL_OPTS from the environment.

node.make_opts

Extra arguments for make when compiling Node.js.

• 类型：字符串
• 默认值：未设置
• 环境变量：MISE_NODE_MAKE_OPTS

When unset, mise uses NODE_MAKE_OPTS from the environment.

node.mirror_url

Base URL that mise downloads Node.js archives and their SHASUMS256.txt checksums from.

• 类型：URL
• 默认值："https://nodejs.org/dist/"
• 环境变量：MISE_NODE_MIRROR_URL

When unset, mise uses NODE_BUILD_MIRROR_URL from the environment, then the default. With the default URL, musl builds come from the unofficial builds site instead. See Unofficial builds.

node.ninja

Build Node.js with ninja instead of make when compiling from source.

• 类型：布尔值
• 默认值：true when ninja is on PATH
• 环境变量：MISE_NODE_NINJA

With ninja, and node.concurrency unset, ninja chooses how many jobs to run in parallel.

node.nodenv_root

Root directory of nodenv, which mise sync node --nodenv imports Node.js versions from.

• 类型：路径
• 默认值："~/.nodenv"
• 环境变量：NODENV_ROOT

node.npm_shim

Wrap each Node.js version's npm so that npm install -g runs mise reshim afterwards.

• 类型：布尔值
• 默认值：true
• 环境变量：MISE_NODE_NPM_SHIM

The wrapper reshims after global installs and uninstalls, so new global commands get shims. It is not installed on Windows. Turn it off to let Corepack or a global npm install -g npm@... manage bin/npm directly. See Global npm packages.

node.nvm_dir

Directory of nvm, which mise sync node --nvm imports Node.js versions from.

• 类型：路径
• 默认值："~/.nvm"
• 环境变量：NVM_DIR

node.verify

Verify downloaded Node.js archives against the SHA-256 checksums in SHASUMS256.txt.

• 类型：布尔值
• 默认值：true
• 环境变量：MISE_NODE_VERIFY

When the lockfile has no checksum for an archive, mise downloads SHASUMS256.txt, checks its OpenPGP signature as node.gpg_verify allows, and records the archive's checksum. Setting this to false skips both the checksum file and its signature check. A checksum already in the lockfile is still verified.