p5.js 友好错误系统（FES）贡献指南：架构解析、函数参考与开发笔记

p5.js 友好错误系统FES贡献指南架构解析、函数参考与开发笔记【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js导读p5.js 的友好错误系统Friendly Error System简称 FES会在控制台输出以 p5.js says: 开头的友好错误消息作为浏览器原生错误信息的补充帮助初学者快速定位代码问题。本文以 contributor_docs/zh-Hans/fes_contribution_guide.md 为主线系统梳理 FES 的整体架构、各个核心函数的职责与调用链、翻译键体系、性能取舍以及已知限制并结合当前仓库源码src/friendly_errors/ 与 translations/en/translation.json给出源码级验证。读完本文你将理解 FES 如何收集错误、如何生成与打印友好消息、如何参与参数验证与全局错误监控并掌握为 FES 做贡献所需的关键入口与测试方法。FES 概览它从哪里收集错误core/friendly_errors当前仓库中为 src/friendly_errors/包含了 p5.js 的友好错误系统代码。FES 从多个位置收集错误文件加载错误与自动播放错误的错误处理库内的参数检查如函数调用时参数数量或类型不正确p5.js 贡献者实现的其他自定义错误处理。生成友好错误消息的主要入口函数有四个p5._friendlyError()将输入消息格式化并打印经由_report()为友好错误p5._validateParameters()验证接收到的输入值是否存在错误类型或缺少值p5._friendlyFileLoadError()指导用户解决与文件加载函数相关的错误p5._friendlyAutoplayError()指导用户解决与浏览器自动播放策略相关的错误。在新版源码中FES 的模块划分如下与旧版相比已有演进下文会逐一说明src/friendly_errors/fes_core.js核心逻辑包含_report()、_friendlyError()、fesErrorMonitor()、checkForUserDefinedFunctions()、helpForMisusedAtTopLevelCode()等src/friendly_errors/param_validator.js参数验证包含validate()、friendlyParamError()、findClosestSchema()等对应旧版validate_params.js的_validateParameters()src/friendly_errors/browser_errors.js浏览器错误分类表errorTable与生命周期入口点列表entryPointssrc/friendly_errors/stacktrace.js解析错误堆栈的代码借用自 stacktrace.jssrc/friendly_errors/fes.jsFES 消息打印基础设施FES.log等与国际化翻译加载。以下示意图展示了 FES 中各文件及函数的连接关系 FES 函数参考_report()控制台输出的最终出口_report()是直接将错误辅助消息输出到控制台的主要函数。注意如果设置了p5._fesLogger即正在运行测试则使用它代替console.log。这在通过 Mocha 运行测试时非常有用——此时_fesLogger会让_report()将错误消息作为字符串交给测试框架与断言的字符串进行比对。语法_report(message); _report(message, func); _report(message, func, color);参数param {String} message 要打印的消息 param {String} [func] 函数名称 param {Number|String} [color] CSS颜色代码[func]输入用于在错误消息末尾附加参考文档链接。从源码看src/friendly_errors/fes_core.js 中mapToReference()链接按函数名自动构造普通函数追加(https://p5js.org/reference/p5/函数名)形式的链接类方法则解析为p5.ClassName形式而以load开头的加载函数不追加参考链接。[color]输入用于设置错误消息的颜色属性在当前版本的友好错误消息中未被使用。位置src/friendly_errors/fes_core.js旧版文档中为core/friendly_errors/fes_core.js。_friendlyError()通用友好错误入口_friendlyError()创建并打印友好错误消息任何 p5 函数都可以调用它来提供友好错误消息。源码中其实现非常简洁src/friendly_errors/fes_core.jsp5._friendlyError function (message, func) { if (p5.disableFriendlyErrors) return; p5._report(message, func); };值得注意的是当p5.disableFriendlyErrors为真时它直接返回在压缩版minified构建中_friendlyError与_checkForUserDefinedFunctions会被替换为空函数源码中通过IS_MINIFIED判断这正是p5.min.js 中禁用 FES的实现方式。_friendlyFileLoadError()文件加载错误引导_friendlyFileLoadError()位于以下加载函数内部image/loading_displaying/loadImage()io/files/loadFont()io/files/loadTable()io/files/loadJSON()io/files/loadStrings()io/files/loadXML()io/files/loadBytes()其调用序列为_friendlyFileLoadError _report语法_friendlyFileLoadError(errorType, filePath);参数param {Number} errorType 文件加载错误类型的编号 param {String} filePath 导致错误的文件路径errorType对应文件加载错误的具体分类目的是针对不同错误场景给出精确、信息丰富的提示——例如无法读取字体文件数据与文件过大无法读取会显示不同的错误信息。当前仓库中加载函数如 src/image/loading_displaying.js 中的loadImage通过图片元素onerror回调捕获失败翻译键位于translations/en/translation.json的fes.fileLoadError下包括image、font、json、table、strings、xml、bytes、gif、large等细分条目以及通用建议suggestion提示检查文件路径、在线托管或运行本地服务器。示例文件加载错误示例/// 缺少字体文件 let myFont; function preload() { myFont loadFont(assets/OpenSans-Regular.ttf); } function setup() { fill(#ED225D); textFont(myFont); textSize(36); text(p5*js, 10, 50); } function draw() {}除了浏览器的不支持错误外FES 还将在控制台中生成以下消息 p5.js says: 看起来加载字体时出现了问题。请检查文件路径(assets/OpenSans-Regular.ttf)是否正确尝试在线托管文件或运行本地服务器。 更多信息https://github.com/processing/p5.js/wiki/Local-server位置旧版位于core/friendly_errors/file_errors.js在当前仓库中文件加载错误的文案已迁移到 translations/en/translation.json 的fes.fileLoadError键下而加载函数内部保留了调用占位如 src/image/loading_displaying.js、src/io/files.js新构建已改为基于加载回调与翻译键生成消息。_friendlyAutoplayError()浏览器自动播放策略如果存在与播放媒体例如视频相关的错误_friendlyAutoplayError()会在内部被调用——这很可能是由于浏览器的自动播放策略所致。它生成并打印友好错误消息对应翻译键为fes.autoplay见 translations/en/translation.json 第 3 行消息会说明媒体未被浏览器允许播放并附上更多信息的链接。位置src/friendly_errors/fes_core.js。_validateParameters()参数数量与类型校验_validateParameters()通过将输入参数与函数文档中的参数信息进行匹配来运行参数验证检查函数调用是否包含正确数量和正确类型的参数。它生成并打印友好错误消息对应翻译键为fes.friendlyParamError.*见 translations/en/translation.json包含type_TOO_FEW_ARGUMENTS、type_TOO_MANY_ARGUMENTS、type_WRONG_TYPE、type_EMPTY_VAR四个模板。可以通过p5._validateParameters(FUNCT_NAME, ARGUMENTS)或p5.prototype._validateParameters(FUNCT_NAME, ARGUMENTS)在需要参数验证的函数内部调用。建议将静态版本p5._validateParameters用于一般用途p5.prototype._validateParameters(FUNCT_NAME, ARGUMENTS)主要用于调试和单元测试。_validateParameters()位于以下模块的函数内accessibility/outputs、color/creating_reading、color/settingcore/environment、core/rendering、core/shape/2d_primitives、core/shape/attributes、core/shape/curves、core/shape/vertex、core/transformdata/p5.TypedDict、dom/domevents/acceleration、events/keyboardimage/image、image/loading_displaying、image/p5.Image、image/pixelio/filesmath/calculation、math/randomtypography/attributes、typography/loading_displayingutilities/string_functionswebgl/3d_primitives、webgl/interaction、webgl/light、webgl/loading、webgl/material、webgl/p5.Camera文档给出的调用序列为validateParameters buildArgTypeCache addType lookupParamDoc scoreOverload testParamTypes testParamType getOverloadErrors _friendlyParamError ValidationError report friendlyWelcome从当前源码src/friendly_errors/param_validator.js看这一机制已升级为基于 Zod 的 schema 验证核心流程为validate()依据 docs/parameterData.json由函数内联文档生成中的重载overloads信息通过generateZodSchemasForFunc()动态构造 Zod schema 并缓存到schemaRegistry校验失败时用findClosestSchema()找出与用户实参最接近的重载 schema对参数个数不匹配的项给予更高权重再用friendlyParamError()生成友好消息。此外param_validator.js还通过p5.registerDecorator为p5.prototype上的方法自动注入参数校验跳过_isUserCall标记的内部调用并提供fn._internal()包装器用于包裹await之后的内部调用。支持的参数类型覆盖基础类型Number、String、Boolean、Function、Array、Integer、Object等、常量通过constantsMap映射到具体值、p5 对象p5.Vector等通过p5Constructors匹配、Web API 对象HTMLElement、MouseEvent等、元组与联合类型。语法_validateParameters(func, args);参数param {String} func 被调用的函数的名称 param {Array} args 用户输入参数示例缺少参数的示例arc(1, 1, 10.5, 10);FES 将在控制台中生成以下消息 p5.js says: [sketch.js, line 13] arc()至少需要6个参数但只收到了4个。 (https://p5js.org/reference/p5/arc)类型不匹配的示例arc(1, ,1, 10.5, 10, 0, Math.PI);FES 将在控制台中生成以下消息 p5.js says: [sketch.js, line 14] arc()的第一个参数需要Number类型但收到了string类型。 (https://p5js.org/reference/p5/arc)位置旧版为core/friendly_errors/validate_params.js当前仓库中为 src/friendly_errors/param_validator.js。fesErrorMonitor()监控浏览器全局错误fesErrorMonitor()监控浏览器错误消息猜测错误的来源并为用户提供额外指导包括堆栈跟踪——即程序中直到抛出错误点为止所调用函数的顺序列表。堆栈跟踪对于判断错误是内部错误还是由用户直接调用的代码引起非常有用。它生成并打印友好错误消息使用的翻译键包括fes.globalErrors.syntax.*、fes.globalErrors.reference.*、fes.globalErrors.type.*见 translations/en/translation.json 的fes.globalErrors节点涵盖notDefined、cannotAccess、invalidToken、unexpectedToken、redeclaredVariable、missingInitializer、badReturnOrYield、notfunc、notfuncObj、readFromNull、readFromUndefined、constAssign等细分类型通过processStack()使用的内部库错误消息fes.wrongPreload、fes.libraryError通过printFriendlyStack()使用的堆栈跟踪消息fes.globalErrors.stackTop、fes.globalErrors.stackSubseq通过handleMisspelling()使用的拼写检查消息来自引用错误fes.misspelling。_fesErrorMonitor()由window上的error事件和未处理的 Promise 拒绝unhandledrejection事件自动触发见 src/friendly_errors/fes_core.js 末尾的事件绑定。也可以在 catch 块中手动调用try { someCode(); } catch (err) { p5._fesErrorMonitor(err); }该函数目前适用于ReferenceError、SyntaxError和TypeError的子集。完整列表位于 src/friendly_errors/browser_errors.js 的errorTable中其中按浏览器差异Chrome、Firefox、Safari为同一类错误登记了不同的消息模板例如变量未定义Chrome 报 X is not definedSafari 报 Cant find variable: X。_fesErrorMonitor的调用序列大致如下_fesErrorMonitor processStack printFriendlyError (if type of error is ReferenceError) _handleMisspelling computeEditDistance _report _report printFriendlyStack (if type of error is SyntaxError、TypeError, etc) _report printFriendlyStack语法fesErrorMonitor(event);参数param {*} e 错误事件示例内部错误示例 1function preload() { // 由于在preload中调用background() // 导致错误 background(200); }FES 将在控制台中生成以下消息 p5.js says: [sketch.js, line 8] 当调用background时p5js库内部发生了一个错误错误信息为无法读取未定义的属性正在读取background。如果没有特别说明这可能是由于从preload调用background导致的。preload函数中除了加载调用loadImage、loadJSON、loadFont、loadStrings等之外不应该有任何其他内容。 (https://p5js.org/reference/p5/preload)内部错误示例 2function setup() { cnv createCanvas(200, 200); cnv.mouseClicked(); }FES 将在控制台中生成以下消息 p5.js says: [sketch.js, line 12] 当调用mouseClicked时p5js库内部发生了一个错误错误信息为无法读取未定义的属性正在读取bind。如果没有特别说明这可能是传递给mouseClicked的参数问题。 (https://p5js.org/reference/p5/mouseClicked)错误示例作用域function setup() { let b 1; } function draw() { b 1; }FES 将在控制台中生成以下消息 p5.js says: [sketch.js, line 5] 当前作用域中未定义b。如果您已在代码中定义它应检查其作用域、拼写和大小写JavaScript区分大小写。 更多信息https://p5js.org/examples/data-variable-scope.html错误示例拼写function setup() { xolor(1, 2, 3); }FES 将在控制台中生成以下消息 p5.js says: [sketch.js, line 2] 您可能不小心写了xolor而不是color。如果您希望使用p5.js中的函数请将其更正为color。 (https://p5js.org/reference/p5/color)位置src/friendly_errors/fes_core.js。从源码看fesErrorMonitor()的工作流程是先从事件对象中提取Error兼容ErrorEvent与PromiseRejectionEvent调用errorStackParser.parse()解析堆栈再由 src/friendly_errors/stacktrace.js 的processStack()判断错误是否源于库内部——其做法是向上回溯堆栈一旦遇到entryPointssetup、draw、mousePressed、keyPressed等用户生命周期入口见 src/friendly_errors/browser_errors.js就截断并判定顶层帧是否来自 p5 库文件随后用errorTable中的消息模板{{}}占位符替换为捕获符号匹配浏览器原始错误文本再按错误类型分支输出对应翻译模板。拼写检查handleMisspelling()使用 Levenshtein 编辑距离阈值EDIT_DIST_THRESHOLD 2在所有公开 p5 符号中寻找最接近的候选命中则给出您可能不小心写了 X 而不是 Y的提示helpForMisusedAtTopLevelCode()则识别在setup()/draw()之外误用 p5 符号的情况。checkForUserDefinedFunctions()检查用户函数的大小写检查是否有任何用户定义的函数setup()、draw()、mouseMoved()等带有大小写错误。它生成并打印友好错误消息对应翻译键为fes.checkUserDefinedFns。语法checkForUserDefinedFunctions(context);参数param {*} context 当前默认上下文。 在全局模式下设置为window 在实例模式下设置为p5实例示例function preload() { loadImage(myimage.png); }FES 将在控制台中生成以下消息 p5.js says: 您可能不小心写了preLoad而不是preload。如果这不是有意的请更正它。 (https://p5js.org/reference/p5/preload)从源码看该函数会先判断是否实例模式再以entryPoints列表建立小写名 - 正确名映射遍历上下文对象的所有属性若某属性的小写形式命中映射、正确大小写的函数不存在、且该属性本身是函数则提示用户写错了大小写。此外在 p5.js 2.0 中若检测到用户定义了preload()会额外提示该函数已在 2.0 移除建议改用async/await或回调在setup()中加载资源。位置src/friendly_errors/fes_core.js。helpForMisusedAtTopLevelCode()顶层代码误用检测helpForMisusedAtTopLevelCode()在窗口加载时由fes_core.js调用以检查在setup()或draw()之外使用 p5.js 函数的情况。它生成并打印友好错误消息对应翻译键为fes.misusedTopLevel。参数param {*} err 错误事件 param {Boolean} log false位置src/friendly_errors/fes_core.js。源码实现中misusedAtTopLevelCode列表是惰性构建的defineMisusedAtTopLevelCode()会遍历 p5 的公开符号排除下划线开头按函数 / 常量 / 变量分类并按名称长度降序排序从而保证命中时能给出最具体的符号提示例如误用HALF_PI时提示HALF_PI而非PI。由于不同浏览器对同一错误的措辞不同Edge 报 PI is undefinedFirefox 报 ReferenceError: PI is undefinedChrome 报 Uncaught ReferenceError: PI is not defined匹配采用正则\W?symbol\W形式并在命中后建议用户将代码移入setup()。 开发笔记已知限制假阳性与假阴性情况在 FES 中可能会遇到两类问题假阳性false positive像虚假警报即 FES 警告有错误但代码实际是正确的假阴性false negative则是代码中有错误但 FES 没有提醒。识别并修复它们很重要因为能节省调试时间、减少困惑并让修复实际问题变得更容易。在某些不理想的情况下错误处理的设计可能需要在消除假阳性与消除假阴性之间取舍如果必须选择通常应优先消除假阳性避免生成分散注意力或误导用户的不正确警告。与fes.globalErrors相关的限制FES 只能检测到使用const或var声明的被覆盖的全局变量使用let声明的变量不会被检测到。这一限制源于let处理变量实例化的特定方式目前无法解决。fesErrorMonitor()下描述的功能目前仅在 Web 编辑器上或在本地服务器上运行时有效相关内容可参见历史 pull request #4730。FES 的性能问题默认情况下p5.js 启用 FES而在p5.min.js中禁用以防止 FES 函数拖慢进程。错误检查系统可能会显著减慢代码在某些情况下最多慢 10 倍。可以在草图顶部用一行代码禁用 FESp5.disableFriendlyErrors true; // 禁用FES function setup() { // 进行设置操作 } function draw() { // 进行绘制操作 }请注意此操作只禁用已知会影响性能的 FES 功能例如参数检查不影响性能的友好错误消息仍保持启用这包括文件加载失败时的详细错误消息以及尝试覆盖全局空间中的 p5.js 函数时的警告。从源码与测试可以进一步印证这一设计src/core/main.js 中disableFriendlyErrors属性文档明确指出FES 会在幕后做额外工作例如检查传入函数的参数禁用后 sketch 绘制性能可显著提升示例中circle(50, 50)本会触发参数数量提示禁用后静默失败。src/friendly_errors/fes_core.js 中_friendlyError()、checkForUserDefinedFunctions()、fesErrorMonitor()均在开头检查if (p5.disableFriendlyErrors) return;src/friendly_errors/param_validator.js 的validate()与注册的装饰器也同样受该开关与p5.disableParameterValidator控制。在压缩构建中_friendlyError与_checkForUserDefinedFunctions会被直接替换为空函数IS_MINIFIED判断test/unit/core/main.js 中分别用_friendlyErrorStub验证了非压缩版会警告globals already exist、压缩版不会调用_friendlyError。未来工作的想法解耦 FESissue #5629消除假阳性情况识别假阴性情况添加更多单元测试以获得全面的测试覆盖更直观、清晰且可翻译的消息友好错误国际化的更多讨论可参见 p5-fes-i18n 手册识别更多常见错误类型并使用 FES 进行泛化例如bezierVertex()、quadraticVertex()必需对象未初始化以及检查nf()、nfc()、nfp()、nfs()的 Number 参数是否为正。结论本文基于贡献指南梳理了core/friendly_errors当前为 src/friendly_errors/的整体组织与用途并对每个核心函数提供了参考说明_report()是控制台输出的最终出口_friendlyError()提供通用入口_friendlyFileLoadError()与_friendlyAutoplayError()分别覆盖文件加载与自动播放场景_validateParameters()负责参数校验新版基于 Zod schema 与 docs/parameterData.jsonfesErrorMonitor()监控浏览器全局错误并配合 src/friendly_errors/stacktrace.js 解析堆栈与 src/friendly_errors/browser_errors.js 的错误分类表checkForUserDefinedFunctions()与helpForMisusedAtTopLevelCode()则处理用户代码的常见误用。所有消息文案均由 translations/en/translation.json 中的fes.*键驱动并支持通过 src/friendly_errors/fes.js 的语言检测与本地缓存机制加载对应语言如fes-zh.json。文章后半部分收录了来自前贡献者的开发笔记涵盖假阳性/假阴性取舍、fes.globalErrors的let检测限制、性能开销与p5.disableFriendlyErrors true;的禁用方式以及解耦 FES、扩充测试覆盖与消息可翻译性等未来方向。此外社区曾于 2021–2022 年开展 FES 专项调查调查结果以漫画与完整报告两种格式公开可作为了解用户真实痛点的一手资料。如果你正在考虑为 FES 做贡献建议从开发笔记中的未来工作的想法入手并借助单元测试验证新增的友好错误行为。【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考