开发环境

CKEditor 5 代码库分为多个 npm 包。主包是 ckeditor5，它安装了所有项目依赖项以及各种与开发相关的资源，例如

测试环境设置，
Yarn 的配置，
翻译管理工具，
文档生成器，
以及发布工具。

主包的 GitHub 仓库还托管所有其他 CKEditor5 子包。

您可以在 CKEditor 5 仓库的 README 中找到所有官方包的列表。

在版本 19.0.0 之前，CKEditor 5 是在多仓库架构中开发的。如果您想使用较旧的多仓库版本，请参考旧的开发环境指南获取面向多仓库的说明。

# 要求

要开始开发 CKEditor 5，您需要

Node.js 18.0.0+
Git

# 设置 CKEditor 开发环境

首先，您需要安装 Yarn 来用它进行依赖管理。

最好在您的系统中全局安装它，以便以后更方便地使用

npm install -g yarn

注意： 阅读如何避免使用 sudo 全局安装包或使用 nvm。

然后克隆 CKEditor 5 仓库

git clone https://github.com/ckeditor/ckeditor5.git
cd ckeditor5

并从 npm 注册表安装所有 CKEditor 5 包。

yarn install

# 运行测试

要运行测试，您需要使用 test 和 manual 任务。

yarn run test --watch --coverage --source-map --files=engine

或者，更简短

yarn run test -- -wcs --files=engine

此命令将运行 ckeditor5-engine 包的测试。

注意： 无法一次性运行所有包的测试并获得代码覆盖率，因为项目的大小（测试文件和源模块的数量）超过了 webpack 的能力（它会耗尽内存）。

要为手动测试创建一个服务器，请使用 manual 任务

yarn run manual

为了帮助测试本地化的编辑器，该任务接受两个可选配置：--language="en" 和 --additionalLanguages="ar,pl,..."。前者设置测试编辑器使用的主要语言。默认情况下它是 "en"，在大多数情况下，您不需要更改它。后者将更多语言引入手动测试，这在处理用户界面中的从右到左语言时很有帮助。

您可以阅读有关测试环境的更多信息。

# 构建 DLL

一些手动测试需要 DLL 构建。要了解有关 DLL 构建的更多信息，请阅读 DLL 构建指南。除非您想专门检查 DLL 构建中的更改，否则它们不需要每次都更新。运行 yarn run manual 将提示您选择是否运行构建。要手动构建它们，您需要运行 dll:build 任务

yarn run dll:build

此任务接受以下参数

--verbose – 显示脚本的完整输出，包括 webpack 输出。即使未使用此参数，也会显示错误。
--dev – 在 webpack 中启用 development 模式并禁用代码最小化，这使得更容易阅读输出。

# 生成文档

要构建文档，您需要运行 docs 任务

yarn run docs

文档将位于 build/docs/ 中。

此任务接受以下参数

--skip-api – 跳过构建 API 文档（这占用了大部分时间）。
--skip-snippets – 跳过构建实时代码片段。
--snippets=snippet-name – 要构建的代码片段。接受与 {@snippet ...} 标记中使用的代码片段名称匹配的通配符模式。例如
```
--snippets=image         // matches roughly {@snippet *image*}
--snippets="features/*"  // matches roughly {@snippet *features/*}
--snippets=classic-editor,build-classic-source
```
注意：如果您要构建的代码片段使用另一个代码片段作为提供编辑器实例的源，则需要指定这两个代码片段（例如，--files=features/default-headings,build-classic-source）。
--skip-validation – 跳过最终的链接验证。
--skip-guides – 跳过构建所有指南，除了允许浏览部分构建文档的 index.md 文件。

--guides=guide-name – 要构建的指南。接受与指南名称匹配的通配符模式。例如

--guides=image         // matches roughly "*image*"
--guides="features/*"  // matches roughly "*features/*"
--guides=features/image

--watch – 在监视模式下运行文档生成器。它涵盖指南，但它不涵盖 API 文档。
--production – 最小化资产并执行在 CKEditor 5 开发过程中不需要的其他操作。
--verbose – 打印更多信息。

yarn run docs --skip-api

构建文档后，您可以快速启动一个 HTTP 服务器来提供服务

yarn run docs:serve

# 验证文档

要验证我们的文档中的所有页面是否都能打开，并且没有任何错误，您不需要手动逐页执行。相反，有一个网络爬虫会自动遍历文档并访问所有已找到的页面。爬虫会打开一个无头 Chromium 浏览器，并将任何找到的错误记录到控制台。

要检查文档中的页面，请先构建它 (yarn run docs)，然后提供服务 (yarn run docs:serve)，最后运行爬虫

yarn run docs:verify

默认情况下，爬虫扫描 http://fake.ckeditor.com:8080，因此您需要先调整您的 hosts 文件。

爬虫会从文档中收集并打开所有链接，除了 API 和资产。

爬虫接受以下参数

--url (别名 -u) – 要开始爬取的 URL。此参数是必需的。借助它，您可以例如验证已部署的文档。
--depth (别名 -d) – 一个数字，定义应该检查多少个嵌套页面级别。默认值为无穷大。
--exclude (别名 -e) – 一个包含 URL 排除项的字符串，与排除部分匹配的链接将被跳过。您可以通过提供多个 --exclude (或 -e) 参数来定义多个排除项。不指定值会删除默认排除项（如果有）。默认情况下，不会排除任何内容，但 docs:verify 脚本有一些预定义的排除项。
--concurrency (别名 -c) – 扫描过程中要使用的并发页面（浏览器标签）数量。默认情况下，所有链接都会一个接一个地打开（并发度为 1）。
--quit (别名 -q) – 一个布尔值参数，指定是否应该在找到第一个错误后立即终止扫描。默认情况下禁用，因此所有找到的链接都会被扫描，无论它们是否有错误。

例如，要检查文档而不使用默认排除项（API 和资产链接），只使用 2 个并发页面，并在找到第一个错误后立即终止扫描，请运行以下命令

yarn run docs:verify -e -c 2 -q

# 定义网络爬虫的排除项

爬虫支持作为文本模式提供的排除项，这些模式将在错误消息中作为子字符串进行搜索。此模式只是一个纯文本，而不是正则表达式。当找到模式（子字符串）时，此类错误将被忽略 - 它不会在扫描完成后列出，也不会将整个扫描标记为失败。只有未被忽略的错误才会在扫描结束时记录。

忽略错误的模式必须在发生错误的页面上的<meta>标签中定义。这个<meta>标签必须具有x-cke-crawler-ignore-patterns名称和content值，该值以JSON对象的形式提供，其中

每个键都是爬虫可以检测到的错误类型。
每个值都是文本或文本数组，用于在错误消息中查找匹配项。特殊通配符值*可用于忽略给定错误类型的全部错误。

支持以下错误类型：uncaught-exception、request-failure、response-failure、console-error、navigation-error和page-crash

uncaught-exception – 正如其名称所示，这些是页面上的未捕获异常。
request-failure – 当请求未发送（例如，被浏览器阻止）或未收到任何响应（例如，由于超时或远程服务器无法访问）时，会发生此错误。从HTTP角度来看，HTTP错误响应（例如404或500）被认为是成功的响应。此类请求不会被记录为请求失败，而是被记录为响应失败。
response-failure – 每个状态码等于或大于400的HTTP响应都被视为失败的响应。
console-error – 所有console.error()调用都被视为错误。
navigation-error – 当以下情况发生时，可能会发生导航错误：
- 存在SSL错误（例如，自签名证书或过期证书的情况）。
- 目标URL无效。
- 在导航到页面时，超时时间已超过，因此未发出load事件（例如，由于JavaScript代码中的无限循环）。
page-crash – 通用页面故障，不属于其他类别（如内存不足）。

错误类型	示例
`uncaught-exception`	`"uncaught-exception": "ckeditor-duplicated-modules"` 此模式仅忽略`ckeditor-duplicated-modules`异常。
`request-failure`	`"request-failure": "missing-file.jpg"` 所有在URL中包含`missing-file.jpg`的请求都将被忽略。
`response-failure`	`"response-failure": "HTTP response status code: 401"` 所有需要授权的请求都将被忽略。
`console-error`	`"console-error": "Example error message"` 所有包含“Example error message”子字符串的控制台错误都将被忽略。
`navigation-error`	`"navigation-error": "Navigation timeout of 15000 ms exceeded"` 未完全加载的链接将被忽略。
`page-crash`	`"page-crash": "Error: Page crashed!"` 此通用文本模式将忽略所有页面崩溃。

这些模式只是作为JSON对象中的键值对添加到页面上的<meta>标签中，这些模式应该在那里生效。

<meta name="x-cke-crawler-ignore-patterns" content='{
    "page-crash": "Error: Page crashed!",
    "uncaught-exception": "ckeditor-duplicated-modules",
    "console-error": "Example error message"
}'>

模式（无论错误类型如何）不必是字符串，也可以定义为字符串（模式）数组，以忽略许多不同的错误。

<meta name="x-cke-crawler-ignore-patterns" content='{
    "console-error": [ "Error 1", "Error 2", "Error 3" ]
}'>

要忽略所有错误，请使用特殊通配符值*

<meta name="x-cke-crawler-ignore-patterns" content='{
    "console-error": "*"
}'>

除了在<meta>标签中定义排除项的可能性外，还可以通过添加data-cke-crawler-skip属性来指定爬虫无法访问链接。

<a href="path/to/page" data-cke-crawler-skip>No entry for crawler, sorry</a>

# 生成内容样式

可以生成一个样式表，其中包含所有CKEditor 5功能带来的内容样式。为此，请执行

yarn docs:content-styles

样式表将保存在build/content-styles文件夹中。

要了解更多信息，请参阅内容样式指南。

# 为贡献者提供的其他信息

# SVG图标

默认情况下，CKEditor 5支持在ckeditor5-*/theme/icons文件夹中找到的SVG图标。不幸的是，大多数SVG编辑软件会生成带有注释、过时标签和复杂路径的输出，这会膨胀DOM并使构建变得过大，毫无意义。

为了删除多余的数据并防止某些问题，您应该在将所有新图标添加到代码库之前优化它们。为此，您可以使用项目根目录中的clean-up-svg-icons脚本，该脚本是SVGO工具的包装器。

cd path/to/ckeditor5

# Optimize all SVG files in the folder.
npm run clean-up-svg-icons path/to/icons/*.svg

# Optimize a single SVG file.
npm run clean-up-svg-icons path/to/icon/icon.svg

该脚本最多可以将图标大小缩减70%，具体取决于用于创建图标的软件以及图像的整体复杂程度。

注意：在使用该脚本之后，您可能仍然需要手动调整SVG文件的源代码。

有时，SVGO会留下空（透明）组<g>...</g>。它们应该从源代码中删除，再次运行clean-up-svg-icons通常可以做到这一点。
确保<path>元素的数量最少。在将文件保存到图像处理器之前，尽可能合并路径。

我们每天都在努力使我们的文档保持完整。您是否发现过时信息？是否缺少某些内容？请通过我们的问题跟踪器报告。

随着42.0.0版本的发布，我们重写了大部分文档以反映新的导入路径和功能。我们感谢您的反馈，这将帮助我们确保文档的准确性和完整性。