2025-10-22 01:40:18 +08:00

8.3 KiB

Raw Blame History

高级配置

虽然 wp-scripts 提供了可靠的默认配置，但在某些情况下可能需要更专业的设置。好消息是 wp-scripts 具有高度适应性。例如，您可以扩展和覆盖默认的 webpack 配置，从而能够添加加载器和插件，或修改构建流程的几乎所有环节。这种灵活性确保当项目规模扩大或需求变化时，wp-scripts 能够根据您不断变化的需求进行定制。

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

扩展资源

@wordpress/scripts（官方文档）
webpack 与 WordPress 包的交互机制（WordPress 开发者博客）

开始使用 wp-scripts

@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 命令。交互式提示将引导您完成设置步骤。您可以按需配置，但当询问 "entry point"（入口点）时，请输入 build/index.js。

当然，使用 wp-scripts 设置项目有多种方式，但这是区块编辑器手册全程推荐的实践方案。

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

npm install @wordpress/scripts --save-dev

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

示例项目文件夹/
├── build/
├── node_modules/ (自动生成)
├── src/
│   └── index.js
├── package-lock.json (自动生成)
└── package.json

基础用法

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

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

随后可以使用 npm run {脚本名称} 命令来运行这些脚本。

使用 `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 中定义的脚本将自动加载（参见示例）。

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

/**
 * 加载编辑器资源。
 */
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 包含了 Jest（一个 JavaScript 测试框架）以及端到端测试和单元测试脚本：

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

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

8.3 KiB Raw Blame History Unescape Escape