title: "开始使用 wp-scripts" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Devenv - Getting Started - Repos

开始使用 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 开发中许多初始设置、配置和样板代码。这样您就可以专注于构建区块和区块编辑器扩展。

快速开始

安装

确保您的计算机已安装 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

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

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

Basic usage

Once installed, you can run the predefined scripts provided with wp-scripts by referencing them in the scripts section of your package.json file. Here’s an example:

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

These scripts can then be run using the command npm run {script name}.

使用 wp-scripts 的构建流程

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

在项目开发时，请使用 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 包含了 JavaScript 测试框架 Jest，以及端到端和单元测试脚本：

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

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

高级配置

虽然 wp-scripts 提供了可靠的默认配置，但有时您可能需要更专业的设置。好消息是 wp-scripts 具有高度适应性。例如，您可以扩展和覆盖默认的 webpack 配置，从而添加加载器和插件，或修改构建过程的几乎所有环节。这种灵活性确保了随着项目发展或需求变化，wp-scripts 能够适应您不断演进的需求。

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

额外资源

• @wordpress/scripts（官方文档）
• webpack 与 WordPress 包如何交互（WordPress 开发者博客）