# Node.js 开发环境

进行区块编辑器开发时，您需要准备 [Node.js](https://nodejs.org/en) 开发工具、代码编辑器以及本地 WordPress 环境（详见[区块开发环境](/docs/getting-started/devenv/README.md)）。Node.js（`node`）是一个开源运行时环境，可让您通过终端（也称为命令行界面 CLI 或 Shell）执行 JavaScript 代码。

安装 `node` 将自动包含 Node 包管理器（`npm`）和 Node 包执行工具（`npx`），这两个工具在区块和插件开发中会频繁使用。

Node 包管理器 ([`npm`](https://docs.npmjs.com/cli/v10/commands/npm)) 具有依赖管理和脚本执行等多重功能，是官方推荐的包管理工具，所有文档中均大量涉及其使用方法。

Node 包执行工具 ([`npx`](https://docs.npmjs.com/cli/v10/commands/npx)) 用于运行未全局安装的软件包命令，在使用 [`create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) 包搭建区块时尤为常用。

## Mac 和 Linux 系统安装 Node.js（通过 `nvm`）

推荐使用 [Node 版本管理器](https://github.com/nvm-sh/nvm)（`nvm`）安装 Node.js。通过该工具可安装并管理特定版本的 `node`，所有版本将本地化安装在用户目录中，有效避免全局权限问题。

以下是通过 `nvm` 安装 `node` 并设置区块开发推荐版本的快速指南，详见[完整安装指南](https://github.com/nvm-sh/nvm#installing-and-updating)。

1.  打开终端执行以下命令安装 `nvm`。macOS 系统默认未安装开发者工具，若出现提示请按指引安装。

```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
```

2.  关闭并重启终端
3.  在终端运行 `nvm install --lts` 安装最新的 [LTS](https://nodejs.org/en/about/previous-releases)（长期支持）版 Node.js
4.  在终端运行 `node -v` 和 `npm -v` 验证安装的 `node` 与 `npm` 版本

如需安装特定版本 `node`，可运行 `nvm install 18` 安装 18 版本，通过 `nvm use [版本号]` 切换不同版本。更多操作详见 `nvm` [使用指南](https://github.com/nvm-sh/nvm#usage)。

部分项目（如 Gutenberg）包含 [`.nvmrc`](https://github.com/WordPress/gutenberg/blob/trunk/.nvmrc) 文件来指定所需 `node` 版本。此时运行 `nvm use` 将自动选择对应版本。若该版本未安装，系统会提示需要安装的版本号，请依次运行 `nvm install [版本号]` 和 `nvm use`。

## Windows 及其他系统安装 Node.js

您可直接从 [Node.js 官网下载安装包](https://nodejs.org/en/download/)，推荐选择最新版本。系统提供 Windows 和 Mac 安装程序，以及 Linux 二进制文件。

微软官方还提供了 [详细指南](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows#install-nvm-windows-nodejs-and-npm)，说明如何在 Windows 和 WSL 中安装 `nvm` 与 Node.js。

## 故障排除

若安装 `node` 时出现 `zsh: command not found: nvm` 错误，可能需要创建默认配置文件。

macOS 系统默认 Shell 为 `zsh`，请在终端运行 `touch ~/.zshrc` 创建配置文件（若文件已存在亦可直接运行）。Ubuntu 系统（含 WSL）默认使用 `bash`，请改用 `touch ~/.bashrc` 命令。完成后重复步骤 2-4。

最新版 `node` 适用于多数开发项目，但请注意某些软件包和工具可能存在特定版本要求。若遇到问题，可能需要安装并使用旧版 `node`。同时请确认项目是否包含 `.nvmrc` 文件，并使用其中指定的 `node` 版本。

## 扩展资源

-   [Node.js](https://nodejs.org/en)（官方文档）
-   [Node 版本管理器](https://github.com/nvm-sh/nvm)（官方文档）
-   [为本地 WordPress 开发安装 Node.js 和 npm](https://learn.wordpress.org/tutorial/installing-node-js-and-npm-for-local-wordpress-development/)（Learn WordPress 教程）