@wordpress/scripts

最后更新：2026-10-17 10:55:29

这是一组专为 WordPress 开发打造的可复用脚本。为方便起见，此软件包中提供的每个工具都附带了内置的推荐配置。

在无缝协作的情况下，完善的命令行界面有助于让项目工作变成更愉快的体验。然而，认为开发者一开始就能轻松选择合适工具，然后确保它们及其所有扩展能够相互兼容，这是一种误导性假设。此外，这还不够，因为开发者需要独自维护所有配置和依赖工具的最新状态。当他们支持多个共享相同配置的项目时，这个问题会成倍增加。

幸运的是，有一种模式可以简化维护者的工作——可复用脚本。其核心思想是将所有必需的配置和脚本迁移到单个工具依赖中。在大多数情况下，应该可以使用默认设置完成所有任务，但也允许一定程度的自定义。有了这些，更新所有项目应该会成为一个非常直接的任务。

此软件包受 react-scripts 和 kcd-scripts 启发。

安装

你只需安装一个 npm 模块：

npm install @wordpress/scripts --save-dev

注意：此软件包需要具有长期支持状态的 Node.js 版本（查看 Active LTS 或 Maintenance LTS 发布版本）。它与旧版本不兼容。

设置

此软件包提供了一个命令行界面，并公开了一个名为 wp-scripts 的可执行文件，因此你可以通过 npm exec --no -- wp-scripts 直接调用它。不过，此模块的设计意图是让你使用项目 package.json 文件中的 scripts 部分进行配置。这个完整示例展示了其中包含的大部分功能。

示例：

{
    "scripts": {
        "build": "wp-scripts build",
        "check-engines": "wp-scripts check-engines",
        "check-licenses": "wp-scripts check-licenses",
        "format": "wp-scripts format",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
        "lint:md:docs": "wp-scripts lint-md-docs",
        "lint:pkg-json": "wp-scripts lint-pkg-json",
        "packages-update": "wp-scripts packages-update",
        "plugin-zip": "wp-scripts plugin-zip",
        "start": "wp-scripts start",
        "test:e2e": "wp-scripts test-e2e",
        "test:unit": "wp-scripts test-unit-js"
    }
}

若要设置使用 ESNext 语法的开发环境，熟悉在 Block Editor 中使用 JavaScript 也可能很有帮助。它非常深入地解释了如何使用 build 和 start 脚本。

更新到新版本

若要将现有项目更新到 @wordpress/scripts 的新版本，请打开更新日志，找到你当前使用的版本（检查项目顶层目录中的 package.json），并按照较新版本的迁移说明进行操作。

在大多数情况下，在 package.json 中升级 @wordpress/scripts 版本，并在项目根目录中运行 npm install 就足够了，但最好检查更新日志以了解潜在的破坏性变更。此软件包还包含 packages-update 脚本，旨在自动化更新项目中 WordPress 依赖的过程。

我们致力于将破坏性变更保持在最低限度，以便尽可能无缝地升级 @wordpress/scripts。

可用脚本

build

根据提供的配置转换你的代码，使其适用于生产环境，并针对最佳性能进行优化。

此脚本在生成单次构建后退出。对于更适合开发的增量构建，请参阅 start 脚本。

用法

示例：

{
    "scripts": {
        "build": "wp-scripts build",
        "build:custom": "wp-scripts build entry-one.js entry-two.js --output-path=custom",
        "build:copy-php": "wp-scripts build --webpack-copy-php",
        "build:custom-directory": "wp-scripts build --source-path=custom-directory"
    }
}

这就是使用上述设置执行该脚本的方式：

npm run build – 构建用于生产环境的代码。
npm run build:custom – 使用两个入口点和一个自定义输出目录构建用于生产环境的代码。自定义入口点的路径相对于项目根目录。
npm run build:copy-php – 构建用于生产环境的代码，并选择将 src 目录及其子文件夹中的所有 PHP 文件复制到输出目录。默认情况下，只会复制在检测到的 block.json 文件的 render 和 variations 字段中列出的 PHP 文件。
npm run build:custom-directory – 使用 custom-directory 作为源代码目录来构建用于生产环境的代码。

此脚本会自动使用优化配置，但有时你可能想指定一些自定义选项：

--webpack-bundle-analyzer – 启用可视化，使用可交互缩放的树图显示 webpack 输出文件的大小。
--webpack-copy-php – 启用将源目录（默认为 src）及其子文件夹中的所有 PHP 文件复制到输出目录。
--webpack-no-externals – 禁用脚本资源生成，并忽略默认 externals 列表。
--blocks-manifest – 生成一个 PHP 文件，其中包含项目中所有 block.json 文件的区块元数据。这有助于提升注册多个区块类型时的性能，因为它允许你在 WordPress 中使用 wp_register_block_metadata_collection() 和 wp_register_block_types_from_metadata_collection()。
--source-path – 允许自定义源目录。当命令中列出了入口点时，默认值为项目根目录 .；否则默认值为 src。
--output-path – 允许自定义输出目录。默认值为 build 文件夹。

对 block.json 的 viewScriptModule 字段的实验性支持可通过
--experimental-modules 选项获得。启用此选项后，script 和 module 字段都将被
编译。viewScriptModule 字段类似于 viewScript 字段，但会编译一个模块，
并且应使用 Modules API 在 WordPress 中注册。

了解更多关于使用构建脚本的信息，以根据你的具体需求优化开发体验。

高级信息

此脚本在幕后使用 webpack。它会在你的软件包顶层目录中查找 webpack 配置，如果找到就会使用该配置。如果没有找到，它会使用 @wordpress/scripts 软件包提供的默认配置。在高级用法部分了解更多。

build-blocks-manifest

此脚本会生成一个 PHP 文件，其中包含项目中所有 block.json 文件的区块元数据。这有助于提升注册多个区块类型时的性能，因为它允许你在 WordPress 中使用 wp_register_block_metadata_collection() 和 wp_register_block_types_from_metadata_collection()。

用法：wp-scripts build-blocks-manifest [options]

选项：

--input：指定输入目录（默认：‘build’）
--output：指定输出文件路径（默认：‘build/blocks-manifest.php’）

示例：

wp-scripts build-blocks-manifest --input=src --output=dist/blocks-manifest.php

此命令将扫描指定输入目录中的 block.json 文件，
将其元数据编译为单个 PHP 文件，并输出到指定
位置。然后，你可以在插件中将此文件与
wp_register_block_metadata_collection() 配合使用：

wp_register_block_metadata_collection(
    plugin_dir_path( __FILE__ ) . 'dist',
    plugin_dir_path( __FILE__ ) . 'dist/blocks-manifest.php'
);

使用此方法可以提升注册多个区块
类型时的性能，尤其是对于包含多个自定义区块的插件。请注意，此
功能仅在 WordPress 6.7 及更高版本中可用。

或者，您可以使用 wp_register_block_types_from_metadata_collection()
通过同一次函数调用，自动注册您的插件中的所有区块类型。
这样，您就无需再为插件中的每个区块类型
调用 register_block_type()。

wp_register_block_types_from_metadata_collection(
    plugin_dir_path( __FILE__ ) . 'dist',
    plugin_dir_path( __FILE__ ) . 'dist/blocks-manifest.php'
);

请注意，此功能仅在 WordPress 6.8 及更高版本中可用。

check-engines

检查当前 node、npm（或 yarn）版本是否与给定的语义化版本范围匹配。如果不满足给定版本，则会输出安装所需版本的信息，并且程序会退出并返回错误代码。

示例：

{
    "scripts": {
        "check-engines": "wp-scripts check-engines"
    }
}

以下是使用上述配置执行该脚本的方式：

npm run check-engines – 检查项目的 package.json 文件中 engines 字段列出的工具的安装版本；如果未指定，则回退到此包所需的 node 版本。

高级信息

它在后台使用 check-node-version，并提供了推荐配置。当您的项目没有 engines 字段时，它会检查此包所需的 Node.js 版本。您可以按照 check-node-version 文档中的说明指定自己的范围。要了解更多信息，请参阅高级用法部分。

check-licenses

验证项目的所有依赖项是否与项目自身的许可证兼容。

示例：

{
    "scripts": {
        "check-licenses": "wp-scripts check-licenses --prod --gpl2 --ignore=abab"
    }
}

标志：

--prod（或 --production）：存在时，仅验证 dependencies，而不验证 devDependencies
--dev（或 --development）：存在时，仅验证 devDependencies，而不验证 dependencies
--gpl2：根据 GPLv2 许可证兼容性进行验证
--ignore=a,b,c：用于在验证时忽略的包名集合，以逗号分隔。该选项主要用于依赖项的 license 字段格式错误的情况。假定任何 ignored 包参数都已经由项目所有者人工审查兼容性。

format

它通过以一致的方式格式化源代码，帮助强制执行文件的编码风格指南（默认对 JavaScript、JSON、TypeScript、YAML 启用）。

示例：

{
    "scripts": {
        "format": "wp-scripts format",
        "format:src": "wp-scripts format ./src"
    }
}

以下是使用上述配置执行该脚本的方式：

npm run format – 格式化整个项目目录中的文件。
npm run format:src – 格式化项目的 src 子文件夹目录中的文件。

当您运行类似于上述 npm run format:src 示例的命令时，您可以提供文件、目录或 glob 语法，或它们的任意组合。

默认情况下，位于 build、node_modules 和 vendor 文件夹中的文件会被忽略。您可以通过将文件和目录添加到项目中的 .prettierignore 文件来自定义忽略列表。

lint-js

帮助强制执行 JavaScript 和 TypeScript 文件的编码风格指南。

示例：

{
    "scripts": {
        "lint:js": "wp-scripts lint-js",
        "lint:js:src": "wp-scripts lint-js ./src"
    }
}

以下是使用上述配置执行该脚本的方式：

npm run lint:js – 检查整个项目目录中的 JavaScript 和 TypeScript 文件。
npm run lint:js:src – 检查项目的 src 子文件夹目录中的 JavaScript 和 TypeScript 文件。

当您运行类似于上述 npm run lint:js:src 示例的命令时，您可以提供文件、目录或 glob 语法，或它们的任意组合。请参阅更多示例。

默认情况下，位于 build、node_modules 和 vendor 文件夹中的文件会被忽略。

高级信息

它使用 ESLint，并采用 @wordpress/eslint-plugin npm 包中定义的一组推荐规则。它会优先检测扁平配置文件（eslint.config.*），如果存在旧版 .eslintrc.* 文件，则会回退使用这些文件。您可以按照 ESLint 配置文档中的说明，使用自己的规则覆盖默认规则。要了解更多信息，请参阅高级用法部分。

ESLint v10 中的破坏性变更：

默认配置路径已从 config/.eslintrc.js 更改为 config/eslint.config.cjs。如果您此前扩展了默认配置，请更新您的导入路径。
--ignore-path CLI 标志已随着 eslintrc 系统一起移除。请改为在扁平配置中使用 ignores 数组。
旧版 .eslintrc.* 回退检测已弃用，并将在未来版本中移除。请迁移到 eslint.config.* 文件。

lint-pkg-json

帮助强制执行 package.json 文件的标准。

示例：

{
    "scripts": {
        "lint:pkg-json": "wp-scripts lint-pkg-json",
        "lint:pkg-json:src": "wp-scripts lint-pkg-json ./src"
    }
}

以下是使用上述配置执行这些脚本的方式：

npm run lint:pkg-json – 检查整个项目目录中的 package.json 文件。
npm run lint:pkg-json:src – 检查项目的 src 子文件夹目录中的 package.json 文件。

当您运行类似于上述 npm run lint:pkg-json:src 示例的命令时，您还可以提供一个或多个要扫描的目录。请参阅更多示例。

默认情况下，位于 build、node_modules 和 vendor 文件夹中的文件会被忽略。

高级信息

它使用 npm-package-json-lint，并采用 @wordpress/npm-package-json-lint-config npm 包中定义的一组推荐规则。您可以按照 npm-package-json-lint wiki 中的说明，使用自己的规则覆盖默认规则。要了解更多信息，请参阅高级用法部分。

lint-md-docs

使用 markdownlint 检查 Markdown 文件的标记，以强制执行标准。

示例：

{
    "scripts": {
        "lint:md:docs": "wp-scripts lint-md-docs"
    }
}

以下是使用上述配置执行该脚本的方式：

npm run lint:md:docs – 检查整个项目目录中的 Markdown 文件。

默认情况下，位于 build、node_modules 和 vendor 文件夹中的文件会被忽略。

高级信息

它使用 markdownlint 和 .markdownlint.json 配置。此配置会调整检查规则以符合 WordPress 标准，您可以使用自己的配置进行覆盖；有关命令行参数，请参阅 markdownlint-cli。

lint-style

帮助强制执行样式文件的编码风格指南。

示例：

{
    "scripts": {
        "lint:style": "wp-scripts lint-style",
        "lint:css:src": "wp-scripts lint-style 'src/**/*.css'"
    }
}

以下是使用上述配置执行该脚本的方式：

npm run lint:style – 检查整个项目目录中的 CSS、PCSS 和 SCSS 文件。
npm run lint:css:src – 仅检查项目的 src 子文件夹目录中的 CSS 文件。

当您运行类似于上述 npm run lint:css:src 示例的命令时，请确保在文件通配符周围加上引号。这样可以确保无论使用何种 shell，都可以使用 globby 的功能（例如 ** globstar）。请参阅更多示例。

默认情况下，位于 build、node_modules 和 vendor 文件夹中的文件会被忽略。

高级信息

它使用 stylelint，并采用符合 WordPress CSS Coding Standards 的 @wordpress/stylelint-config 配置。你可以按照 stylelint 用户指南中的说明，使用自己的规则覆盖它们。更多信息请参阅高级用法部分。

packages-update

将项目中使用的 WordPress 软件包更新到最新版本。

示例：

{
    "scripts": {
        "packages-update": "wp-scripts packages-update",
        "postpackages-update": "npm run build"
    }
}

该脚本提供以下自定义选项：

--dist-tag – 允许在更新 npm 软件包时指定自定义 dist-tag。默认值为 latest。这在使用 @wordpress/dependency-extraction-webpack-plugin 时特别有用。它允许安装给定 WordPress 主版本所使用的 npm 依赖版本，以便进行本地测试等。示例：wp-scripts packages-update --dist-tag=wp-6.0。

高级信息

该命令通过扫描 package.json 文件来检测名称以 @wordpress/ 开头的项目依赖项。默认情况下，它会执行 npm install @wordpress/package1@latest @wordpress/package2@latest ... --save，将软件包版本更改为最新版本。你可以在运行该命令时使用 --dist-tag 选项选择不同于 latest 的 dist-tag。

plugin-zip

为 WordPress 插件创建 zip 文件。

示例：

{
    "scripts": {
        "plugin-zip": "wp-scripts plugin-zip"
    }
}

默认情况下，它使用 Plugin Handbook 最佳实践来发现文件。

高级信息

如果插件作者想要自定义包含在 zip 文件中的文件，可以按照 npm-packlist 软件包中的文档说明，在 package.json 文件中提供 files 字段，示例：

{
    "files": [ "dir" ]
}

它复用与 npm pack 命令相同的逻辑来创建 npm 软件包 tarball。

以下是在 zip 文件内创建自定义根文件夹的方法。

更新插件时，WordPress 期望 zip 文件根目录中有一个与插件名称匹配的文件夹。因此请注意，这可能会影响插件更新流程。
--root-folder – 向 zip 文件添加自定义根文件夹。
npm run plugin-zip – 默认情况下，解压插件的 zip 文件后会得到一个与插件同名的文件夹。
npm run plugin-zip --root-folder='custom-directory' – 插件的 zip 文件将被解压到名为 custom-directory 的文件夹中。
npm run plugin-zip --no-root-folder – 这将创建一个内部没有文件夹的 zip 文件，插件文件将直接解压到目标目录中。

start

根据提供的配置转换你的代码，使其准备好进行开发。如果你对代码进行修改，该脚本会自动重新构建，并且你可以在控制台中查看构建错误。

如需更适合生产环境的单次构建，请参阅 build 脚本。

用法

示例：

{
    "scripts": {
        "start": "wp-scripts start",
        "start:hot": "wp-scripts start --hot",
        "start:custom": "wp-scripts start entry-one.js entry-two.js --output-path=custom",
        "start:copy-php": "wp-scripts start --webpack-copy-php",
        "start:custom-directory": "wp-scripts start --source-path=custom-directory"
    }
}

以下是使用上述配置执行该脚本的方式：

npm start – 启动开发构建。
npm run start:hot – 启动带有“Fast Refresh”的开发构建。如果你修改文件，页面将自动重新加载。
npm run start:custom – 启动包含两个入口点和自定义输出目录的开发构建。自定义入口点路径相对于项目根目录。
npm run start:copy-php – 启动开发构建，并选择将 src 目录及其子文件夹中的所有 PHP 文件复制到输出目录。默认情况下，只会复制检测到的 block.json 文件中 render 和 variations 字段列出的 PHP 文件。
npm run start:custom-directory – 使用 custom-directory 作为源代码目录构建生产环境代码。

该脚本会自动使用优化配置，但有时你可能希望指定一些自定义选项：

--hot – 启用“Fast Refresh”。如果你修改代码，页面将自动重新加载。目前，它要求 WordPress 启用 SCRIPT_DEBUG 标志，并安装 Gutenberg 插件。
--no-watch – 启动开发构建，但不启动监听器。
--webpack-bundle-analyzer – 通过可交互缩放的树状图可视化 webpack 输出文件的大小。
--webpack-copy-php – 允许将源目录（默认为 src）及其子文件夹中的所有 PHP 文件复制到输出目录。
--webpack-devtool – 控制 source map 的生成方式。选项请参见 https://webpack.js.org/configuration/devtool/#devtool。
--webpack-no-externals – 禁用脚本资产生成，并省略默认 externals 列表。
--blocks-manifest – 生成一个 PHP 文件，其中包含项目中所有 block.json 文件的区块元数据。这有助于在注册多个区块类型时提升性能，因为它允许你在 WordPress 中使用 wp_register_block_metadata_collection() 和 wp_register_block_types_from_metadata_collection()。
--source-path – 允许自定义源目录。当命令中列出了入口点时，默认值为项目根目录 .，否则为 src。
--output-path – 允许自定义输出目录。默认值为 build 文件夹。

对 block.json viewScriptModule 字段的实验性支持可通过
--experimental-modules 选项获得。启用该选项后，script 和 module 字段都将被
编译。viewScriptModule 字段类似于 viewScript 字段，但会编译一个 module，
并且应在 WordPress 中使用 Modules API 注册。

了解更多关于使用构建脚本的信息，以根据你的具体需求优化开发体验。

高级信息

该脚本在底层使用 webpack。它会在你的软件包顶层目录中查找 webpack 配置，如果找到则会使用该配置。如果没有找到，它会使用 @wordpress/scripts 软件包提供的默认配置。更多信息请参阅高级用法部分。

test-unit-js

运行一次使用方已安装的 Vitest。请在拥有测试的项目中安装测试运行器。

对于新的测试配置，请安装 Vitest 5 和 Vite 8：

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

如果你的项目已经使用 Vite 7 或 8，请保留现有版本，只安装 vitest@^5。

{
    "scripts": {
        "test:unit": "wp-scripts test-unit-js",
        "test:unit:help": "wp-scripts test-unit-js --help",
        "test:unit:watch": "wp-scripts test-unit-js --watch",
        "test:unit:debug": "wp-scripts test-unit-js --inspect-brk --no-file-parallelism",
        "test:unit:update": "wp-scripts test-unit-js --update"
    }
}

默认环境是 Node。必须显式导入 Vitest API。Vitest 会识别 *.test.* 和 *.spec.* 文件。名为 test/index.js 的文件需要重命名，或者需要在使用方配置中显式指定 test.include 模式。

Vitest 会在当前工作目录中先发现 vitest.config.*，然后发现 vite.config.*。Vitest 配置优先于 Vite 配置；它不会自动合并两者。使用 --config path/to/config.mjs 可选择其他文件。ESM 和 TypeScript 配置使用 Vite 的配置加载器。Jest 配置文件以及 package.json 中的 jest 字段不会配置此命令。

@wordpress/scripts 不提供 Vitest 预设、共享设置、DOM 环境、React 转换、别名、控制台断言或 CSS 模拟。有关经过测试的 Node、jsdom 和 Browser Mode 示例、依赖项以及支持范围，请参阅使用方迁移指南。

test-unit-jest

这是一个仅维护型适配器，适用于项目内安装的 Jest 30。它会转发 Jest CLI 参数，并保留其退出状态，同时将 NODE_ENV 和 BABEL_ENV 设置为 test。Vitest 仍然通过 test-unit-js 保持默认。目前没有移除该适配器的计划。

npm install --save-dev jest@30.5.0

在你的 npm test 命令中使用 wp-scripts test-unit-jest。Jest 会自动发现项目的配置；对于自定义文件名，例如 jest-unit.config.js，请传入 --config。Scripts 不再捆绑 Jest、jsdom、WordPress Jest 预设、其 Babel 转换器，或其 GitHub Actions 报告器。

现有测试套件可以继续使用这些已发布的 WordPress Jest 包。维护工作涵盖此适配器和文档中记录的旧版设置。新的测试功能将面向 Vitest。

默认的 wp-scripts lint-js 配置也切换到了 Vitest。Jest 升级清单涵盖了测试命令、依赖项、Jest 配置以及完整的 ESLint 配置。你可以在不安装 Vitest 或 Vite 的情况下保留 Jest 测试。

test-e2e

别名：test-playwright

启动由 Playwright 提供支持的端到端（E2E）测试运行器。它提供了用于控制无头浏览器的高级 API。test-playwright 仍然作为运行相同命令的别名提供。

请参阅入门指南以了解如何编写测试。

示例：

{
    "scripts": {
        "test:e2e": "wp-scripts test-e2e",
        "test:e2e:help": "wp-scripts test-e2e --help",
        "test:e2e:debug": "wp-scripts test-e2e --debug"
    }
}

下面介绍如何使用上述设置执行这些脚本：

npm run test:e2e – 运行所有测试。
npm run test:e2e:help – 输出所有可用于配置测试运行器的选项。
npm run test:e2e:debug – 使用 Playwright 检查器以交互方式运行所有测试。
npm run test:e2e FILE_NAME – 运行特定测试文件。
npm run test:e2e -- --watch – 以监视模式和增强调试功能交互式运行所有测试。

默认情况下，Playwright 会在项目根级别的 /specs 文件夹中查找带有 .test 或 .spec 后缀的 JavaScript 或 TypeScript 文件，例如 /specs/login-screen.wrong-credentials.spec.ts。

该脚本会自动检测启动 Playwright 的最佳配置，但有时你可能需要指定自定义选项。
为此，你可以在包的顶级目录中（与 package.json 同级）添加一个名为 playwright.config.ts 或 playwright.config.js 的文件。

测试失败产物

测试失败时，系统会对页面进行快照，并将其存储在项目根目录的 artifacts/ 目录中。这些快照可帮助在开发过程中或 CI 环境中运行测试时调试失败的测试。

可以通过将 WP_ARTIFACTS_PATH 环境变量设置为项目根目录中所需目录的相对路径来自定义 artifacts/ 目录。例如：要将默认目录从 artifacts/ 更改为 my/custom/artifacts，可以使用 WP_ARTIFACTS_PATH=my/custom/artifacts npm run test:e2e。

高级信息

你可以使用 Playwright 的所有CLI 选项。你也可以运行 ./node_modules/.bin/wp-scripts test-e2e --help 或 npm run test:e2e:help（如上所述）来查看所有可用选项。要了解更多信息，请参阅高级用法部分。

传递 Node.js 选项

wp-scripts 支持完整的 Node.js CLI 选项。它们可以在 wp-scripts 命令之后、脚本名称之前传递。

wp-scripts [NODE_OPTIONS] script

调试测试

对于 Vitest 测试，请在 test-unit-js 之后传入 --inspect-brk --no-file-parallelism。Vitest 随后会在测试工作进程中打开检查器。如果在命令之前传入 --inspect-brk，则会检查包装器进程。

任何支持 Chrome DevTools Protocol 的检查器客户端都可以调试测试。

对于单元测试，请将检查器标志放在 test-unit-js 之后，以便它们传递到 Vitest 工作进程。完整命令设置请参阅使用方迁移指南。

以下示例使用 Google Chrome 和 Visual Studio Code。

在 Google Chrome 中调试

在任意测试中放置 debugger; 语句，然后运行 wp-scripts test-unit-js --inspect-brk --no-file-parallelism（或上面提到的 npm run test:unit:debug）。

然后在 Google Chrome 中打开 about:inspect，并在你的进程上选择 inspect。

测试工作进程会在执行前暂停，以便你附加调试器。在开发者工具中恢复执行。当 Vitest 执行到 debugger; 语句时，执行会再次暂停，以便你检查作用域和调用栈。

在 Visual Studio Code 中调试

自版本 1.23 起，Visual Studio Code 开箱即支持调试 npm 脚本，并可用于调试 Vitest 单元测试。

要在 Visual Studio Code 中运行测试，请确保在 package.json 文件中将 wp-scripts test-unit-js --inspect-brk --no-file-parallelism 保存为 test:unit:debug。

调试时，点击编辑器行号左侧边距中的某一行，在测试中设置断点。

然后在资源管理器中打开 npm 脚本，或在命令面板中运行 Explorer: Focus on NPM Scripts View 以查看 npm 脚本。要启动测试，请点击 test:unit:debug 旁边的调试图标。

测试将开始运行，执行会在你选择的行上暂停，以便你在编辑器中检查当前作用域和调用栈。

有关使用 Visual Studio Code 调试器的更多详细信息，请参阅在 Visual Studio Code 中调试。

使用构建脚本

build 和 start 命令在底层使用 webpack。webpack 用于打包和优化 Web 应用代码，使开发者能够高效管理依赖、提升性能并简化开发工作流。

列出入口点

列出 JavaScript 入口点的最简单方式是将它们作为命令参数传递。

示例：

wp-scripts build entry-one.js entry-two.js

源文件的默认位置是项目根目录。因此，上面的命令将在项目根目录中查找 entry-one.js 和 entry-two.js，并将生成的文件输出到 build 目录。

自动检测 block.json 与源代码目录

对于区块，一个方便的替代方案是使用自动入口点检测。在这种情况下，会扫描源代码目录（默认为 ./src）及其子目录中是否存在 block.json 文件。如果找到一个或多个文件，元数据中列出的 JavaScript 文件将被视为入口点，并会输出到 build 目录中的相应文件夹。block.json 中的 script 字段应传递相对于同一文件夹中 block.json 的相对路径。

示例：

{
    "editorScript": "file:index.js",
    "script": "file:script.js",
    "viewScript": "file:view.js"
}

这样就可以创建多个区块，并使用通过简单命令触发的单一构建流程：

wp-scripts build

可以使用 --source-path 标志自定义源目录，并使用 --output-path 标志自定义输出目录。

回退入口

如果未找到 block.json 文件，回退入口为 src/index.js（其他支持的扩展名：.jsx、.ts 和 .tsx）。在该场景下，生成的输出将写入 build/index.js。

在 JavaScript 中导入样式

示例：

// index.scss
$body-color: red;

.wp-block-my-block {
    color: $body-color;
}

/* style.css */
.wp-block-my-block {
    background-color: black;
}

// index.js
import './index.pcss';
import './index.scss';
import './style.css';

当你使用默认命令 wp-scripts build 运行构建时（同样适用于 start），除了在 build 文件夹中生成的 JavaScript 文件 index.js 之外，你还应看到另外两个文件：

index.css – 所有导入的 CSS 文件会被打包到一个以入口点命名的块中，入口点默认为 index.js，因此创建的文件为 index.css。这用于仅在编辑器中使用的样式。
style-index.css – 导入的 style.css 文件（适用于 PCSS、SASS 和 SCSS 扩展名）会被打包到一个 style-index.css 文件中，该文件旨在同时用于前端和编辑器。

例如，当项目有两个入口点时：

wp-scripts build entry-one.js entry-two.js

在这种情况下，基于 JavaScript 代码中的导入语句生成的 CSS 将遵循入口点的名称：entry-one.css 和 entry-two.css。

重要：避免在入口点名称中使用 style 关键字，否则可能会破坏你的构建过程。

你也可以通过在扩展名前添加 .module 前缀来打包 CSS 模块，例如 style.module.scss。否则，这些文件会像所有其他 style.scss 一样处理。它们也会被提取到 style-index.css 中。

使用字体和图像

可以从由 webpack 控制的 CSS 中引用字体（woff、woff2、eot、ttf 和 otf）和图像（bmp、png、jpg、jpeg、gif 和 wepb）文件，如前一节所述。

示例：

/* style.css */
@font-face {
    font-family: Gilbert;
    src: url( ../assets/gilbert-color.otf );
}
.wp-block-my-block {
    background-color: url( ../assets/block-background.png );
    font-family: Gilbert;
}

使用 SVG

示例：

import starUrl, { ReactComponent as Star } from './star.svg';

const App = () => (
    <div>
        <img src={ starUrl } alt="star" />
        <Star />
    </div>
);

高级用法

通常应将该软件包与一组推荐的配置文件一起使用。虽然可以覆盖提供的每个配置文件，但如果你必须这样做，说明你的用例比预期复杂得多。如果发生这种情况，最好避免使用整个抽象层，并自行设置项目，以完全控制所使用的工具。

默认 webpack 配置

@wordpress/scripts 捆绑了 WordPress 编辑器用作基础的默认 webpack 配置。默认项如下：

入口：通过扫描位于 src 目录中的 block.json 文件里的所有 script 字段，检测项目的入口点。如果未找到 block.json 文件，回退入口为 src/index.js（其他支持的扩展名：.jsx、.ts 和 .tsx）。
输出：build/[name].js，例如：build/index.js，或 build/my-block/index.js。
加载器：
- babel-loader 允许使用 Babel 和 webpack 转译 JavaScript 和 TypeScript 文件。
- @svgr/webpack 和 url-loader 使得可以在 JavaScript 代码中处理 SVG 文件。
- css-loader 与 postcss-loader 和 sass-loader 链式配合，可让 webpack 处理 JavaScript 文件中引用的 CSS、SASS 或 SCSS 文件。
插件（其中包括）：
- CopyWebpackPlugin 会将在 src 目录中发现的所有 block.json 文件复制到构建目录。
- MiniCssExtractPlugin 会将 CSS 提取到单独的文件中。它会为每个包含 CSS 的 JavaScript 入口点创建一个 CSS 文件。
- @wordpress/dependency-extraction-webpack-plugin 使用默认配置，以确保 WordPress 提供的脚本不会包含在构建的包中。

提供你自己的 webpack 配置

如果你在某些情况下想提供自己的 webpack 配置，可以这样做。build 和 start 命令会在以下情况使用你提供的文件：

命令接收到 --config 参数。示例：wp-scripts build --config my-own-webpack-config.js。
项目的顶层目录中存在名为 webpack.config.js 或 webpack.config.babel.js 的文件（与 package.json 同级）。

扩展 webpack 配置

要扩展提供的 webpack 配置，或替换提供的 webpack 配置中的子部分，你可以提供自己的 webpack.config.js 文件，require 提供的 webpack.config.js 文件，并使用 spread 运算符导入提供的配置的全部或部分内容。

在下面的示例中，项目根文件夹中添加了一个 webpack.config.js 文件，它扩展了提供的 webpack 配置，包含使用 toml 解析模块源码并将其转换为 JavaScript 对象的自定义逻辑。这可能有助于在不需要特定加载器的情况下，将 toml 或其他非 JSON 文件作为 JSON 导入：

const toml = require( 'toml' );
const defaultConfig = require( '@wordpress/scripts/config/webpack.config' );

module.exports = {
    ...defaultConfig,
    module: {
        ...defaultConfig.module,
        rules: [
            ...defaultConfig.module.rules,
            {
                test: /.toml/,
                type: 'json',
                parser: {
                    parse: toml.parse,
                },
            },
        ],
    },
};

如果你采用这种方式，请注意：

你应该继续使用 wp-scripts 命令（start 和 build）。不要直接使用 webpack。
此软件包的未来版本可能会更改我们捆绑的 webpack 和 Babel 插件、默认配置等。如果这些更改是必要的，它们将记录在软件包的 CHANGELOG 中，因此请务必在升级前阅读它。

为此软件包做贡献

这是一个独立软件包，是 Gutenberg 项目的一部分。该项目以 monorepo 形式组织。它由多个自包含软件包组成，每个软件包都有特定用途。此 monorepo 中的软件包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解更多关于为此软件包或整个 Gutenberg 做贡献的信息，请阅读项目的主要贡献者指南。