### 高级配置

虽然 `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"
    }
}
```

单元测试验证代码的独立单元（例如函数）是否按预期工作，而端到端测试通过模拟真实用户场景来评估整个项目，确保系统的所有部分无缝协作。