first commit

2025-10-22 01:33:45 +08:00
commit 2080fa3878
251 changed files with 47081 additions and 0 deletions
--- a/getting-started/devenv/README.md
+++ b/getting-started/devenv/README.md
@@ -0,0 +1,61 @@
+# 区块开发环境
+
+本指南将帮助您搭建合适的开发环境，用于创建扩展和修改WordPress区块编辑器的区块及其他插件。
+
+区块开发环境包含在计算机上成功进行区块编辑器开发所需的工具。以下三项是基本要求：
+
+- [区块开发环境](#区块开发环境)
+  - [代码编辑器](#代码编辑器)
+  - [Node.js开发工具](#nodejs开发工具)
+  - [本地WordPress环境](#本地wordpress环境)
+
+<div class="callout callout-info">
+    若想为Gutenberg项目本身做贡献，请参阅<a href="https://developer.wordpress.org/block-editor/contributors/code/getting-started-with-code-contribution">代码贡献指南</a>中的补充文档。
+</div>
+
+## 代码编辑器
+
+代码编辑器用于编写代码。您可以使用任何熟悉的编辑器，关键是要具备打开、编辑和保存文本文件的功能。
+
+如果您还没有偏好的代码编辑器，[Visual Studio Code](https://code.visualstudio.com/)（VS Code）是核心贡献者中进行JavaScript开发的流行选择。它完美兼容三大主流平台（Windows、Linux和Mac），是微软积极维护的开源软件。VS Code还拥有活跃的社区提供插件和扩展支持，其中包含许多适用于WordPress开发的工具。
+
+## Node.js开发工具
+
+Node.js（`node`）是一个开源运行时环境，允许您在网络浏览器之外执行JavaScript。虽然并非所有WordPress JavaScript开发都需要Node.js，但在使用现代JavaScript工具和进行区块编辑器开发时它必不可少。
+
+Node.js及其配套开发工具使您能够：
+
+-   安装并运行区块编辑器开发所需的WordPress包，例如`wp-scripts`
+-   使用`wp-env`和`@wp-playground/cli`搭建本地WordPress环境
+-   使用最新ECMAScript特性并以ESNext规范编写代码
+-   对JavaScript代码进行格式检查、格式化与测试
+-   使用`create-block`包快速创建自定义区块
+
+其功能远不止于此。虽然现代JavaScript开发可能具有挑战性，但WordPress提供了[`wp-scripts`](/docs/getting-started/devenv/get-started-with-wp-scripts.md)和[`create-block`](/docs/getting-started/devenv/get-started-with-create-block.md)等工具来简化流程，这些都得益于Node.js开发工具的支持。
+
+**区块开发推荐使用Node.js的[Active LTS](https://nodejs.org/en/about/previous-releases)（长期支持）版本**。但有时您可能需要使用不同版本。强烈推荐使用`nvm`等Node.js版本管理工具，它允许您在需要时切换`node`版本。您还需要Node包管理器（`npm`）和Node包执行工具（`npx`）来处理某些WordPress包，这两者会随Node.js自动安装。
+
+为了使用Node.js工具和[WordPress提供的开发包](https://github.com/WordPress/gutenberg/tree/trunk/packages)进行区块开发，您需要在计算机上配置合适的Node.js运行时环境。具体设置方法请参考以下链接：
+
+-   [在Mac和Linux上安装Node.js](/docs/getting-started/devenv/nodejs-development-environment.md#node-js-installation-on-mac-and-linux-with-nvm)
+-   [在Windows上安装Node.js](/docs/getting-started/devenv/nodejs-development-environment.md#node-js-installation-on-windows-and-others)
+
+## 本地WordPress环境
+
+本地WordPress环境（站点）为开发提供了受控、高效且安全的空间，让您可以在部署到生产站点之前构建和测试代码。WordPress的相同[运行要求](https://en-gb.wordpress.org/about/requirements/)也适用于本地站点。
+
+在更广泛的WordPress社区中，有许多工具可用于在计算机上搭建本地WordPress环境。本《区块编辑器手册》重点介绍由WordPress项目自身维护的开源工具`wp-env`，它也是Gutenberg开发的推荐工具。
+
+具体设置说明请参阅[`wp-env`入门指南](/docs/getting-started/devenv/get-started-with-wp-env.md)。
+
+<div class="callout callout-info">
+    在本手册中，您可能还会看到对<code><a href="https://github.com/WordPress/wordpress-playground/tree/trunk/packages/playground/cli">@wp-playground/cli</a></code>的引用。这是一个由<a href="https://developer.wordpress.org/playground/">WordPress Playground</a>驱动的轻量级工具，可简化本地WordPress环境的搭建。虽然仍处于实验阶段，但该工具非常适合快速测试WordPress版本、插件和主题。
+</div>
+
+以下列举了部分备选方案（若您不想使用`wp-env`）：
+
+- [WordPress Studio](https://developer.wordpress.com/studio/)
+- [Local](https://localwp.com/)
+- [XAMPP](https://www.apachefriends.org/)
+- [MAMP](https://www.mamp.info/en/mamp/mac/)
+- [Varying Vagrant Vagrants](https://varyingvagrantvagrants.org/)（VVV）
--- a/getting-started/devenv/get-started-with-create-block.md
+++ b/getting-started/devenv/get-started-with-create-block.md
@@ -0,0 +1,95 @@
+# 使用 create-block 快速入门
+
+WordPress 区块编辑器的自定义区块通常通过插件注册，并由特定文件集合定义。[`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) 是官方支持的脚手架工具，可快速生成创建和注册区块所需的文件结构。它能生成项目初始代码，并集成现代化的 JavaScript 构建环境（使用 [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/)），无需额外配置。
+
+该工具包旨在帮助开发者遵循 WordPress 最佳实践快速搭建区块开发环境。
+
+## 快速开始
+
+### 安装配置
+
+请先确保计算机已安装 Node.js 和 `npm`。若未安装，请查阅 [Node.js 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/)指南。
+
+您可以在任意目录使用 `create-block` 创建区块脚手架，然后在生成的插件文件夹内[使用 `wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/) 创建本地 WordPress 开发环境，该环境会自动安装并激活您的新区块插件。
+
+若已搭建[本地 WordPress 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment)，请通过终端进入 `plugins/` 目录。
+
+执行以下命令创建示例区块插件：
+
+```bash
+npx @wordpress/create-block@latest todo-list
+cd todo-list
+```
+
+其中提供的 `slug` 参数（`todo-list`）将作为插件文件夹名称和内部区块标识。
+
+进入本地 WordPress 的插件管理页面，激活 "Todo List" 插件后，即可在编辑器中找到该示例区块。
+
+### 基础使用
+
+`create-block` 默认采用现代 JavaScript（ESNext 与 JSX）构建区块，这需要构建步骤将代码编译为浏览器可识别的格式。幸运的是，`wp-scripts` 工具包已自动处理此过程。关于该工具的详细介绍请参阅 [wp-scripts 入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts)。
+
+当 `create-block` 生成区块脚手架时，会自动安装 `wp-scripts` 并将常用脚本添加到区块的 `package.json` 文件中，默认包含：
+
+```json
+{
+    "scripts": {
+		"build": "wp-scripts build",
+		"format": "wp-scripts format",
+		"lint:css": "wp-scripts lint-style",
+		"lint:js": "wp-scripts lint-js",
+		"packages-update": "wp-scripts packages-update",
+		"plugin-zip": "wp-scripts plugin-zip",
+		"start": "wp-scripts start"
+	}
+}
+```
+
+这些脚本可通过 `npm run {脚本名称}` 命令运行。最常使用的两个脚本是 `start` 和 `build`，它们负责构建流程。
+
+开发区块时请运行 `npm run start` 命令，这将启动开发服务器并在检测到代码变更时自动重新构建。
+
+准备部署区块时请运行 `npm run build` 命令，该命令会对代码进行优化并生成生产环境版本。
+
+各脚本的详细说明请参阅 `wp-scripts` 的[工具包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
+
+## 其他实现方式
+
+### 交互模式
+
+为偏好引导式操作的开发者，`create-block` 提供了交互模式。此模式会逐步提示输入配置参数，无需像前文示例那样手动预先指定 `slug` 等所有选项。
+
+运行以下命令启用此模式：
+
+```bash
+npx @wordpress/create-block@latest
+```
+
+根据提示逐步完成区块设置即可。
+
+### 快速启动模式（选项参数）
+
+若您已熟悉 `create-block` 的[选项参数](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#options)并希望快速完成配置，可使用快速启动模式。通过命令行直接传递特定参数，省去交互提示步骤。
+
+例如，要快速创建命名空间为 "my-plugin"、区块标识为 "my-block" 的动态区块，可使用：
+
+```bash
+npx @wordpress/create-block@latest --namespace="my-plugin" --slug="my-block" --variant="dynamic"
+```
+
+### 使用模板
+
+`create-block` 支持模板功能，允许基于预定义配置和结构创建区块。当您有特定区块结构偏好，或需构建多个相似配置的区块时，此功能尤为实用。
+
+使用模板时，需通过 `--template` 选项指定模板名称或路径：
+```bash
+npx @wordpress/create-block --template="my-custom-template"
+```
+
+模板需预先设置以确保 `create-block` 能正确识别。更多细节请参阅 `create-block` 的[模板文档](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#template)，并查阅[外部项目模板指南](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/)。
+
+## 扩展资源
+
+- [使用 create-block 工具](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)（Learn WordPress 教程）
+- [@wordpress/create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)（官方文档）
+- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)（官方文档）
--- a/getting-started/devenv/get-started-with-wp-env.md
+++ b/getting-started/devenv/get-started-with-wp-env.md
@@ -0,0 +1,144 @@
+# 开始使用 wp-env
+
+[@wordpress/env](https://www.npmjs.com/package/@wordpress/env) 包（简称 `wp-env`）可帮助您快速搭建本地 WordPress 环境（站点），用于插件和主题的开发测试，无需任何额外配置。
+
+在按照本指南操作前，请先确保已安装 [Node.js 开发工具](/docs/getting-started/devenv#node-js-development-tools)。
+
+![wp-env 基础架构图](https://developer.wordpress.org/files/2023/10/wp-env-diagram.png)
+
+## 快速开始
+ 
+1. 根据操作系统说明下载、安装并启动 [Docker Desktop](https://www.docker.com/products/docker-desktop)
+2. 在终端中运行 `npm -g install @wordpress/env` 全局安装 `wp-env`
+3. 在终端中进入现有插件目录、主题目录或新建工作目录
+4. 运行 `wp-env start` 启动本地 WordPress 环境
+5. 脚本运行完成后，访问 <code>http://localhost:8888/wp-admin</code>，使用用户名 `admin` 和密码 `password` 登录 WordPress 管理后台
+
+## 配置 Docker Desktop
+
+`wp-env` 工具使用 [Docker](https://www.docker.com/) 创建运行本地 WordPress 站点的虚拟机。Docker Desktop 应用程序对小型企业、个人用户、教育机构和非商业开源项目免费。详见官方 [FAQ](https://docs.docker.com/desktop/faqs/general/#do-i-need-to-pay-to-use-docker-desktop)。
+
+点击对应链接下载并安装适用于您操作系统的 Docker Desktop：
+
+- [Mac 版 Docker Desktop](https://docs.docker.com/desktop/install/mac-install/)
+- [Windows 版 Docker Desktop](https://docs.docker.com/desktop/install/windows-install/)
+- [Linux 版 Docker Desktop](https://docs.docker.com/desktop/install/linux-install/)
+
+若使用早于 20.04.1 的 Ubuntu 版本，请参阅下方的[故障排除说明](#ubuntu-docker-setup)。
+
+成功安装后启动 Docker Desktop 应用程序，按提示完成设置。通常使用推荐（默认）设置即可，创建 Docker 账户为可选步骤。
+
+## 安装并运行 `wp-env`
+
+`wp-env` 工具用于通过 Docker 创建本地 WordPress 环境。配置好 Docker Desktop 后，在终端中运行以下命令安装 `wp-env`：
+
+```sh
+npm -g install @wordpress/env
+```
+
+此命令将全局安装 `wp-env`，使该工具可在任意目录运行。可通过运行 `wp-env --version` 验证安装，成功会显示版本号。
+
+接着在终端中进入现有插件目录、主题目录或新建工作目录，运行：
+
+```sh
+wp-env start
+```
+
+脚本执行完毕后，即可通过 <code>http://localhost:8888</code> 访问本地环境。使用用户名 `admin` 和密码 `password` 登录 WordPress 管理后台。
+
+<div class="callout callout-tip">
+    部分项目（如 Gutenberg）包含特定的 <code>wp-env</code> 配置，文档可能会要求您运行 <code>npm run wp-env start</code> 命令
+</div>
+
+有关控制 Docker 环境的更多信息，请参阅 [@wordpress/env 包](/packages/env/README.md) 说明文档。
+
+### 运行环境配置
+
+`wp-env` 工具几乎可在任意目录运行。在开发单个插件时，在插件所在目录执行 `wp-env start` 可自动挂载并激活该插件。此规则同样适用于主题开发目录。
+
+若在非插件/主题目录运行 `wp-env start`，将创建通用 WordPress 环境。此时脚本会显示以下警告，若属预期行为可忽略：
+
+```
+!! 警告：未找到 .wp-env.json 配置文件，且无法判定“DIR”是否为 WordPress 安装目录、插件或主题
+```
+
+您还可以通过 `.wp-env.json` 配置文件创建支持多插件和/或主题的环境。详细配置说明请参阅 [@wordpress/env 包](/packages/env/README.md#wp-envjson) 文档。
+
+### 卸载或重置 `wp-env`
+
+以下是一些操作指南，适用于需要重新开始或希望移除已安装内容的情况。
+
+-   如果只需重置并清理 WordPress 数据库，请运行 `wp-env clean all`
+-   若要完全移除特定项目的本地环境，请运行 `wp-env destroy`
+-   若要全局卸载 `wp-env` 工具，请运行 `npm -g uninstall @wordpress/env`
+
+## 故障排除
+
+### 常见错误
+
+使用 `wp-env` 时，常见错误提示：`执行 docker-compose 命令时出错`
+
+-   请检查 Docker Desktop 是否已启动并正在运行。
+-   查看 Docker Desktop 控制面板中的日志，重启或移除现有的虚拟机。
+-   然后尝试重新运行 `wp-env start`。
+
+如果出现错误：`主机已被其他容器占用`
+
+-   您尝试启动的容器已在运行，或者存在其他容器占用。您可以通过在启动该容器的目录中运行 `wp-env stop` 来停止现有容器。
+-   如果不记得启动 `wp-env` 的目录，可以通过运行 `docker stop $(docker ps -q)` 停止所有容器。此操作会停止所有 Docker 容器，请谨慎使用。
+-   然后尝试重新运行 `wp-env start`。
+
+### Ubuntu Docker 设置
+
+如果您使用的 Ubuntu 版本早于 20.04.1，在使用 `wp-env` 设置本地 WordPress 环境时可能会遇到错误。
+
+要解决此问题，请先按照 Docker 的[安装指南](https://docs.docker.com/install/linux/docker-ce/ubuntu/)进行操作。同时需要安装 `docker-compose`，您可能需要单独安装。请参阅 [Docker compose 文档](https://docs.docker.com/compose/install/)。
+
+安装 Docker 和 `wp-env` 后，假设 `wp-env` 已全局配置，尝试在某个目录中运行 `wp-env start`。如果遇到以下错误：
+
+```
+错误：无法在 http+docker://localhost 连接到 Docker 守护进程——它是否正在运行？
+
+如果它位于非标准位置，请使用 DOCKER_HOST 环境变量指定 URL。
+```
+
+首先，请确保 Docker 正在运行。可以通过运行 `ps -ef | grep docker` 来检查，应返回类似以下内容：
+
+```
+/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
+```
+
+如果 Docker 未运行，请尝试通过运行 `sudo systemctl start docker.service` 启动服务。
+
+如果 Docker 正在运行，但未监听 WordPress 环境的通信方式。请尝试添加以下服务覆盖文件以包含对 `tcp` 的监听。有关如何配置 Docker 守护进程的远程访问，请参阅 [Docker 文档](https://docs.docker.com/config/daemon/remote-access/)。
+
+```
+# /etc/systemd/system/docker.service.d/override.conf
+[Service]
+ExecStart=
+ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376
+```
+
+从命令行重启服务：
+
+```
+sudo systemctl daemon-reload
+sudo systemctl restart docker.service
+```
+
+重启服务后，设置环境变量 `DOCKER_HOST` 并尝试启动 `wp-env`：
+
+```
+export DOCKER_HOST=tcp://127.0.0.1:2376
+wp-env start
+```
+
+现在您的环境应设置在 <code>http://localhost:8888</code>。
+
+## 其他资源
+
+- [@wordpress/env](https://www.npmjs.com/package/@wordpress/env)（官方文档）
+- [Docker Desktop](https://docs.docker.com/desktop)（官方文档）
+- [使用 wp-env 快速轻松地进行本地 WordPress 开发](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/)（WordPress 开发者博客）
+- [wp-env：简单的 WordPress 本地环境](https://make.wordpress.org/core/2020/03/03/wp-env-simple-local-environments-for-wordpress/)（Make WordPress Core 博客）
+- [`wp-env` 基础示意图](https://excalidraw.com/#json=8Tp55B-R6Z6-pNGtmenU6,_DeBR1IBxuHNIKPTVEaseA)（Excalidraw）
--- a/getting-started/devenv/get-started-with-wp-scripts.md
+++ b/getting-started/devenv/get-started-with-wp-scripts.md
@@ -0,0 +1,150 @@
+### 高级配置
+
+虽然 `wp-scripts` 提供了可靠的默认配置，但在某些情况下可能需要更专业的设置。好消息是 `wp-scripts` 具有高度适应性。例如，您可以扩展和覆盖默认的 webpack 配置，从而能够添加加载器和插件，或修改构建流程的几乎所有环节。这种灵活性确保当项目规模扩大或需求变化时，`wp-scripts` 能够根据您不断变化的需求进行定制。
+
+有关所有配置选项，请参阅 `wp-scripts` 的[包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
+
+## 扩展资源
+
+- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)（官方文档）
+- [webpack 与 WordPress 包的交互机制](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/)（WordPress 开发者博客）
+
+# 开始使用 wp-scripts
+
+[`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) 包（通常简称为 `wp-scripts`）是一组配置文件和脚本，主要旨在标准化和简化需要 JavaScript 构建步骤的 WordPress 项目的开发流程。
+
+JavaScript 构建步骤指的是将 JavaScript 源代码和相关资源转换、打包并优化为适合生产环境格式的过程。这些构建步骤通常会将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的版本，还可以将多个文件打包成一个，通过代码压缩减小文件大小，并执行各种其他任务来优化代码。
+
+在为区块编辑器开发时，您通常会使用 ESNext 和 JSX，区块编辑器手册中的所有示例都采用这些语法。学习如何设置构建步骤至关重要，但配置 [webpack](https://webpack.js.org/)、[Babel](https://babeljs.io/) 和 [ESLint](https://eslint.org/) 等必要工具可能变得复杂。这正是 `wp-scripts` 的用武之地。
+
+以下是 `wp-scripts` 能够实现的功能：
+
+- **代码编译：** 使用 Babel 将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的代码
+- **资源打包：** 使用 webpack 将多个 JavaScript 文件合并为单一包以提升性能
+- **代码检查：** 提供 ESLint 配置，帮助确保代码质量并符合编码规范
+- **代码格式化：** 集成 Prettier 实现自动化代码风格统一，保持项目间代码格式一致性
+- **Sass 编译：** 将 Sass（.scss 或 .sass）文件转换为标准 CSS
+- **代码压缩：** 为生产环境缩减 JavaScript 代码体积，确保更快的页面加载速度
+
+该软件包封装了现代 WordPress JavaScript 开发中大量初始设置、配置和样板代码，让您可以专注于构建区块和区块编辑器扩展功能。
+
+## 快速开始
+
+<div class="callout callout-tip">
+    如果您使用 <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/"><code>@wordpress/create-block</code></a> 包来搭建创建和注册区块所需的文件结构，您将同时获得现代化的 JavaScript 构建设置（使用 <code>wp-scripts</code>）且无需任何配置，因此无需担心安装 <code>wp-scripts</code> 或注册资源。详细信息请参阅<a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/">开始使用 <code>create-block</code></a>。
+</div>
+
+### 安装步骤
+
+请确保计算机已安装 Node.js 和 `npm`。若未安装，请查阅 [Node.js 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/)指南。
+
+接着创建项目文件夹，确保其中包含 `package.json` 文件、`build` 文件夹和 `src` 文件夹。`src` 文件夹内还需包含 `index.js` 文件。
+
+如果尚未创建 `package.json` 文件，请在终端中进入项目文件夹并运行 `npm init` 命令。交互式提示将引导您完成设置步骤。您可以按需配置，但当询问 "entry point"（入口点）时，请输入 `build/index.js`。
+
+当然，使用 `wp-scripts` 设置项目有多种方式，但这是区块编辑器手册全程推荐的实践方案。
+
+最后，通过以下命令将 `wp-scripts` 包安装为开发依赖项：
+
+```bash
+npm install @wordpress/scripts --save-dev
+```
+
+安装完成后，您的项目文件夹结构应如下所示：
+
+```bash
+示例项目文件夹/
+├── build/
+├── node_modules/ (自动生成)
+├── src/
+│   └── index.js
+├── package-lock.json (自动生成)
+└── package.json
+```
+
+### 基础用法
+
+安装完成后，您可以通过在 `package.json` 文件的脚本部分引用 `wp-scripts` 提供的预定义脚本来运行它们。以下是一个示例：
+
+```json
+{
+    "scripts": {
+        "start": "wp-scripts start",
+        "build": "wp-scripts build"
+    }
+}
+```
+
+随后可以使用 `npm run {脚本名称}` 命令来运行这些脚本。
+
+### 使用 `wp-scripts` 的构建流程
+
+您最常使用的两个脚本是 `start` 和 `build`，因为它们负责构建步骤。有关所有选项，请参阅[包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
+
+在开发项目时，使用 `npm run start` 命令。这将启动开发服务器，并在检测到任何更改时自动重新构建项目。请注意，`build/index.js` 中的编译代码不会被优化。
+
+当您准备部署项目时，使用 `npm run build` 命令。这会优化您的代码，使其适合生产环境。
+
+构建完成后，您将看到在 `build/index.js` 中创建的编译后的 JavaScript 文件。
+
+构建过程中还会生成一个 `build/index.asset.php` 文件，其中包含依赖项数组和一个版本号（用于缓存清除）。请注意，如果没有使用 `wp-scripts` 构建流程注册块，您需要手动创建 `*.asset.php` 依赖文件（参见[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-no-build-e621a6)）。
+
+### 加载资源
+
+如果您通过 `register_block_type` 注册块，`block.json` 中定义的脚本将自动加载（参见[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)）。
+
+要在编辑器或其他上下文中手动加载文件，可以参考[在编辑器中加载资源](https://developer.wordpress.org/block-editor/how-to-guides/enqueueing-assets-in-the-editor/)指南获取更多信息。以下是一个典型的实现示例：
+
+```php
+/**
+ * 加载编辑器资源。
+ */
+function example_project_enqueue_editor_assets() {
+    $asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
+
+    wp_enqueue_script(
+        'example-editor-scripts',
+        plugins_url( 'build/index.js', __FILE__ ),
+        $asset_file['dependencies'],
+        $asset_file['version']
+    );
+}
+add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );
+```
+
+这里有一个在编辑器中手动加载文件的[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8)。
+
+## 后续步骤
+
+虽然 `start` 和 `build` 是两个最常用的脚本，但 `wp-scripts` 还提供了其他几个有用的工具，值得探索。以下是一些示例。
+
+### 保持代码质量
+
+为了帮助开发者提高代码质量，`wp-scripts` 预配置了 ESLint 和 Prettier 等工具。ESLint 确保您的 JavaScript 遵循最佳实践和 [WordPress 编码标准](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/)，而 Prettier 会自动格式化您的代码。可用的脚本包括：
+
+```json
+{
+    "scripts": {
+        "format": "wp-scripts format",
+        "lint:css": "wp-scripts lint-style",
+        "lint:js": "wp-scripts lint-js",
+    }
+}
+```
+
+定期对代码进行格式化和检查可以确保代码功能正常、清晰且易于维护，无论是您自己还是其他开发者都能受益。
+
+### 运行测试
+
+除了编写代码，验证其功能也至关重要。`wp-scripts` 包含了 [Jest](https://jestjs.io/)（一个 JavaScript 测试框架）以及端到端测试和单元测试脚本：
+
+```json
+{
+    "scripts": {
+        "test:e2e": "wp-scripts test-e2e",
+        "test:unit": "wp-scripts test-unit-js"
+    }
+}
+```
+
+单元测试验证代码的独立单元（例如函数）是否按预期工作，而端到端测试通过模拟真实用户场景来评估整个项目，确保系统的所有部分无缝协作。
--- a/getting-started/devenv/nodejs-development-environment.md
+++ b/getting-started/devenv/nodejs-development-environment.md
@@ -0,0 +1,49 @@
+# 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 教程）