@wordpress/scripts 包，通常称为 wp-scripts，是一组配置文件和脚本，主要旨在标准化并简化需要 JavaScript 构建步骤的 WordPress 项目的开发过程。

JavaScript 构建步骤是指将 JavaScript 源代码及相关资源转换为适合生产环境的格式的过程。这些构建步骤通常会将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的版本。它们还可以将多个文件打包成一个，压缩代码以减少文件大小，并执行各种其他任务来优化代码。

在为区块编辑器构建时，您通常会使用 ESNext 和 JSX，且区块编辑器手册中的所有示例都是用这些语法编写的。学习如何设置构建步骤至关重要。然而，配置必要的工具（如 webpack、Babel 和 ESLint）可能会变得复杂。这就是 wp-scripts 发挥作用的地方。

以下是 wp-scripts 可以完成的一些任务：

  • 编译：使用 Babel 将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的代码。
  • 打包：使用 webpack 将多个 JavaScript 文件组合成一个包，以获得更好的性能。
  • 代码检查：提供 ESLint 配置以帮助确保代码质量和符合编码标准。
  • 代码格式化：集成 Prettier 进行自动化代码样式设置，以保持项目中一致的代码格式。
  • Sass 编译：将 Sass（.scss 或 .sass）文件转换为标准 CSS。
  • 代码压缩：减小生产环境中 JavaScript 代码的大小，以确保更快的页面加载。

该包抽象了与为现代 WordPress 进行 JavaScript 开发相关的许多初始设置、配置和样板代码。然后您可以专注于构建区块和区块编辑器扩展。

快速开始

如果您使用 @wordpress/create-block 包来搭建创建和注册区块所需的文件结构，您还将获得无需配置的现代 JavaScript 构建设置（使用 wp-scripts），因此您无需担心安装 wp-scripts 或加载资源。有关更多详细信息，请参阅 使用 create-block 快速开始。

安装

确保您的计算机上已安装 Node.js 和 npm。如果没有，请查看 Node.js 开发环境 指南。

然后，创建一个项目文件夹，并确保其中包含 package.json 文件、build 文件夹和 src 文件夹。src 文件夹还应包含一个 index.js 文件。

如果您之前没有创建过 package.json 文件，请在终端中导航到项目文件夹并运行 npm init 命令。交互式提示将引导您完成步骤。根据您的喜好进行配置，但当它询问“入口点”时，请输入 build/index.js。

当然，使用 wp-scripts 设置项目的方法有很多，但这是区块编辑器手册中推荐的方法。

最后，通过运行以下命令将 wp-scripts 包作为开发依赖项安装：

npm install @wordpress/scripts --save-dev

安装完成后，您的项目文件夹应如下所示：

example-project-folder/
├── build/
├── node_modules/ (autogenerated)
├── src/
│   └── index.js
├── package-lock.json (autogenerated)
└── package.json

基本用法

安装后，您可以通过在 package.json 文件的 scripts 部分引用它们来运行 wp-scripts 提供的预定义脚本。示例如下：

{
    "scripts": {
        "start": "wp-scripts start",
        "build": "wp-scripts build"
    }
}

然后可以使用命令 npm run {script name} 运行这些脚本。

使用 wp-scripts 的构建过程

您最常使用的两个脚本是 start 和 build，因为它们处理构建步骤。有关所有选项，请参阅 包文档。

在处理项目时，请使用 npm run start 命令。这将启动开发服务器，并在检测到任何更改时自动重新构建项目。请注意，build/index.js 中的编译代码不会进行优化。

当您准备好部署项目时，请使用 npm run build 命令。这将优化您的代码并使其适合生产环境。

构建完成后，您将在 build/index.js 处看到创建的编译 JavaScript 文件。

在构建过程中还会创建一个 build/index.asset.php 文件，其中包含依赖项数组和版本号（用于缓存清除）。请注意，如果您想在没有此 wp-scripts 构建过程的情况下注册区块，您需要手动创建 *.asset.php 依赖项文件（参见 示例）。

加载资源

如果您通过 register_block_type 注册区块，block.json 中定义的脚本将自动加载（参见 示例）。

要在编辑器中手动加载文件，或在任何其他上下文中，您可以参考 在编辑器中加载资源 指南以获取更多信息，但这里是一个典型的实现。

/**
 * Enqueue Editor assets.
 */
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' );

以下是 在编辑器中手动加载文件的示例。

下一步

虽然 start 和 build 将是最常用的两个脚本，但 wp-scripts 还附带了几个值得探索的其他有用工具。以下是其中几个的概览。

维护代码质量

为了帮助开发人员提高代码质量，wp-scripts 预配置了 ESLint 和 Prettier 等工具。ESLint 确保您的 JavaScript 遵循最佳实践和 WordPress 编码标准，而 Prettier 会自动格式化您的代码。可用的脚本包括：

{
    "scripts": {
        "format": "wp-scripts format",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
    }
}

定期检查和格式化您的代码可确保其功能正常、清晰且易于您和其他开发人员维护。

运行测试

wp-scripts test-unit-js 运行您项目中安装的 Vitest 以进行单元测试。对于新的测试设置，请将 Vitest 5 和 Vite 8 作为开发依赖项安装：

npm install --save-dev vitest@^5 vite@^8

如果您的项目已经使用 Vite 7 或 8，请保留它们并仅安装 vitest@^5。

wp-scripts 还提供 Playwright 用于端到端测试。将这些命令添加到 package.json：

{
    "scripts": {
        "test:e2e": "wp-scripts test-e2e",
        "test:unit": "wp-scripts test-unit-js"
    }
}

单元测试检查单个函数或组件。端到端测试通过用户交互检查应用程序。

有关 Vitest 配置和示例（包括 DOM 和浏览器测试）的信息，请参阅 消费者迁移指南。现有的 Jest 项目可以使用 wp-scripts test-unit-jest 并遵循 保留现有的 Jest 套件 以获取所需的依赖项和配置。

高级配置

虽然 wp-scripts 提供了完善的默认配置，但在某些情况下您可能需要更专业的设置。好消息是 wp-scripts 具有极高的可适应性。例如，您可以扩展并覆盖默认的 webpack 配置，从而添加加载器和插件或修改构建过程的几乎任何部分。这种灵活性确保随着项目增长或其需求变化，wp-scripts 可以量身定制以满足您不断变化的需求。

有关所有配置选项，请参阅 wp-scripts 包文档。

其他资源