后端【免费下载链接】formidableThe most used, flexible, fast and streaming parser for multipart form data. Supports uploading to serverless environments, AWS S3, Azure, GCP or the filesystem. Used in production.项目地址https://gitcode.com/gh_mirrors/fo/formidable点击查看免费下载formidable是 Node.js 生态中广泛使用的 multipart/form-data 流式解析库。本文以仓库根目录 CHANGELOG.md 为骨架逐版本还原从 v1.0.12 到 3.5.4 的关键演进脉络并对照 src/Formidable.js、src/FormidableError.js、src/parsers/Multipart.js 及test-node/standalone/下的测试用例讲清每个版本变更背后的实现原理。读完本文你将掌握 formidable 3.x 的文件大小限制体系、Promise 化解析、目录上传、安全加固措施与错误码体系并能借助 CHANGELOG 快速定位源码中的对应实现。版本演进总览根据 VERSION_NOTES.md 与 CHANGELOGformidable 的版本线大致可分为三个阶段v1 系列2010–2018最初由 Felix Geisendörfer 为 Transloadit 开发已长期废弃NPM 上的formidablev1不再维护、不回补安全修复。v2 系列代号formidablev2/v2-latest基于 Modern Streams API 重写引入 Plugins API、filter选项与错误码体系要求 Node.js 10。v3 系列当前主线master分支formidablelatest全量切换 ES Modules移除options.multiplesfields/files恒为数组并持续进行安全加固要求更高版本 Node.jsREADME 注明 Node.js 20package.json 的 engines 声明为 14.0.0。CHANGELOG 中最新的 3.5.4 版本对应 package.json 中的version: 3.5.4说明仓库快照与日志头部一致。整体来看3.x 的主线节奏是3.0.0 完成架构断代3.1.x–3.4.0 补齐功能3.5.x 聚焦安全与工程化收尾。3.5.x安全加固与工程化收尾3.5.4修复os.machine兼容性与 CI 矩阵3.5.4 修复了os.machine破坏部分依赖方的问题issue #994并将 Node 16、18、20、22 纳入 CI/CD。os.machine()是 Node 16.4 之后才稳定暴露的 API若在不支持它的运行时被调用会导致崩溃。仓库内 .github/workflows/main.yml 承载了这套多版本 CI 矩阵配合 .github/workflows/codeql-analysis.yml 做安全扫描。3.5.3ZAST.AI 安全报告与 cuid2 随机名生成3.5.3 是一次以安全为核心的版本其要点包括根据 ZAST.AI 的安全报告修复若干漏洞重点是随机文件名生成用久经实战考验的paralleldrive/cuid2替代原先基于 hexoid 的命名方案更新失败测试、CI/CD 工作流与 Actions、CodeQL 安全分析 Action、README 与徽章。随机文件名生成是文件上传解析的关键安全点若文件名可预测攻击者可能构造路径冲突甚至目录遍历。当前实现位于 src/Formidable.js通过cuid2init({ length: 25, fingerprint: ... })初始化一个 25 字符的 CUID2 生成器fingerprint由NODE_ENV、os.platform()与os.hostname()组合而成默认命名逻辑_getNewName直接调用createId()生成随机名src/Formidable.js。CHANGELOG 强调仍是 25 字符长度因此对存量使用者不构成破坏性变更但更安全、更快。依赖声明见 package.json 中的paralleldrive/cuid2: 2.2.2。3.5.2 与 3.5.1打包兼容与解析器防挂起3.5.2修复了 webpack 环境下导入 hexoid 的困难#982。该修复发生在 v3 全面 ES Modules 化的背景下属于打包器兼容性收尾。3.5.1修复了 multipart 解析器的一个核心缺陷flush 或 fail绝不挂起#945。对应实现是 src/parsers/Multipart.js 的_flush(done)方法当流结束时若正处于HEADER_FIELD_START且index 0或正处于PART_DATA且index this.boundary.length则补齐partEnd与end回调否则只要状态不是END就报malformedMultipart错误。这一点有专门测试佐证test-node/standalone/multipart_parser.test.js 用残缺的 multipart 报文--_\r\n--_--\r\n验证解析器会抛出malformedMultipart而不会无限等待。3.5.0双包发布——ESM 与 CommonJS 并存3.5.0 引入双包Dual package支持既可作为 ES moduleimport也可作为 CommonJSrequire。仓库的 package.json 通过exports字段同时声明import指向./src/index.js与require指向./dist/index.cjs两条入口构建产物由tool/rollup.config.js经pnpm run build-package生成prepublishOnly钩子保证发布前自动构建。3.4.0form.parse的 Promise 化3.4.0 让form.parse(req)在不传回调时直接返回 Promise并以[fields, files]数组形式 resolve。这在 src/Formidable.js 的parse方法中实现当cb缺省时内部构造一个 Promise并把 resolve/reject 包进回调随后所有error/end事件统一走once(dezalgo(cb))dezalgo与once见 src/utils.js确保回调至多执行一次且不会同步抛错。对应测试 test-node/standalone/promise.test.js 验证了两个方向成功时promise.then(([fields, files]) ...)拿到对象失败时如故意设置minFileSize: 10 ** 6Promise 以httpCode 400、code errors.smallerThanMinFileSize的FormidableErrorreject。这意味着从 3.4.0 起await form.parse(req)成为官方推荐写法const form formidable({ uploadDir: __dirname }); const [fields, files] await form.parse(req);3.3.xcreateDirsFromUploads与目录上传3.3.2 新增options.createDirsFromUploads配合uploadDir与filename选项即可实现整目录上传HTML 端使用input typefile namefolders webkitdirectory directory multiple。该选项让 formidable 在写入前自动创建目标子目录。实现位于 src/Formidable.js 的_newFile当createDirsFromUploads为 true 时调用createNecessaryDirectoriesAsync(filepath)它基于decorateForceSequential包装fsPromises.mkdir(dirname, { recursive: true })src/Formidable.js从而保证并发上传时多个 mkdir 顺序执行、不互相竞争目录创建失败会抛出cannotCreateDir错误httpCode 409。测试 test-node/standalone/createDirsFromUploads.test.js 用filename: () x/y/z.txt验证了x、x/y、x/y/z.txt三级目录的自动创建。同一版本还让form.parse成为 async 函数未提供回调时忽略其返回的 Promise并新增 e2e 基准测试benchmark目录同时被标记为 npmlatest。3.2.x构建完整的文件限制体系3.2.0 是 3.x 中选项语义变化最密集的版本核心是把“全局总大小”与“单文件大小”彻底分离选项3.2.0 后的语义默认值见 src/Formidable.jsmaxFileSize每个文件的大小上限200 * 1024 * 1024200MBmaxFiles允许上传的文件总数Infinity3.2.0 新增当前代码默认 1000见下注maxTotalFileSize一批文件的总大小上限默认等于maxFileSize向后兼容undefined构造时回落到maxFileSizeminFileSize单文件最小大小11 字节allowEmptyFiles是否允许空文件false实现上src/Formidable.js 的构造函数在maxTotalFileSize未提供时令其等于maxFileSize_handlePart中分别维护fileSize单文件与_totalFileSize累计逐块累加并各自校验src/Formidable.js对应错误码为biggerThanTotalMaxFileSize413、biggerThanMaxFileSize413、smallerThanMinFileSize400、noEmptyFiles400。注CHANGELOG 记载 3.2.0 时maxFiles默认为Infinity当前仓库代码3.5.4中该默认值已调整为1000与 README 一致使用时应以实际安装版本为准。同版本的“错误重命名”指把误命名为maxFileSize的“总大小”错误更正为maxTotalFileSize相关错误这正是 2.0.0 引入的“code httpCode 错误体系”的延续见后文。3.2.5maxFiles超限提前失败3.2.5 让maxFiles超限时尽早报错而不是等整个流处理完。当前实现是_setUpMaxFilessrc/Formidable.js监听fileBegin事件计数一旦超过maxFiles立即_errorhttpCode 413错误码maxFilesExceeded。与之对称的_setUpMaxFieldssrc/Formidable.js在field事件上做同样的提前拦截。3.2.4keepExtensions的一致性修复3.2.4 统一了文件扩展名清洗规则扩展名在第一个非法字符处截断。所谓非法字符指除.、数字和a-Z含大小写之外的所有字符。该修复只影响“未使用filename选项且启用了keepExtensions”的场景。对应实现为 src/Formidable.js 的invalidExtensionChar判断与 src/Formidable.js 的_getExtension后者支持多段复合扩展名a.b.c→.b.c区别于path.extname只取.c并从首个非法字符处截断、过滤掉纯.的伪扩展名。默认命名路径_getNewName会拼接${name}${this._getExtension(originalFilename)}src/Formidable.js。3.2.3 / 3.2.2 / 3.2.1事件与资源清理3.2.3end事件保证只发射一次。当前_maybeEndsrc/Formidable.js通过this.ended与_flushing双重条件避免重复触发测试 test-node/standalone/end-event-emitted-twice.test.js 精确断言end在事件监听与 parse 回调中各只出现一次。3.2.2纯重构#801。3.2.1出错时不留空文件。此前_error中file.destroy()src/Formidable.js对文件流的销毁可能不及时src/PersistentFile.js 的destroy()在销毁写流后通过fs.unlink(filepath)延迟清理磁盘文件。3.1.xhelpers 与错误补充3.1.0新增两个辅助函数firstValues与readBooleans。前者从 3.0.0 起“字段恒为数组”的结果中取首个值且可传入exceptions保留仍需要数组的字段如select multiple实现见 src/helpers/firstValues.js后者把 HTML 表单 checkbox 的on值转换为布尔值实现见 src/helpers/readBooleans.js。README 中给出了配套使用示例firstValues(form, fieldsMultiple, exceptions)之后再readBooleans(fieldsSingle, expectedBooleans)。3.1.1让 JSON 插件支持顶层 JSON 数组、字符串与数字此前仅支持对象。3.1.4补上缺失的pluginFailed错误并改用显式 Node.js 导入node:前缀。3.1.5修复PersistentFile.toString()当前实现返回PersistentFile: newFilename, Original: originalFilename, Path: filepathsrc/PersistentFile.js。3.0.0ES Modules 与破坏性变更3.0.0 是 v3 的断代版本涉及多项破坏性变更移除options.multiples#730。此前的“单值/多值”开关被废弃因为 3.x 中fields与files的取值恒为数组。内部改用现代URLSearchParams解析查询串随之移除qs与querystring两个依赖。带[]的字段名不再享受特殊处理不再自动按数组展开。全量使用 ES Modules#727package.json的type: modulepackage.json即源于此。options.enabledPlugins必须直接包含插件函数本身而不是插件名字符串。默认插件集合定义在 src/Formidable.js 的DEFAULT_OPTIONS中即[octetstream, querystring, multipart, json]均可从 src/plugins/index.js 导入构造时若enabledPlugins过滤后为空会抛missingPlugin错误src/Formidable.js。2.0.0里程碑式重构2.0.0 为 3.x 奠定了几乎所有基础能力CHANGELOG 中记录的主要变更包括文件检测逻辑从“基于文件名”改为“基于是否携带 mimetype”——_handlePart中if (!part.mimetype)即视为字段src/Formidable.js。新增options.filter在文件落盘前过滤返回 false 即跳过该 part文档明确“不会让 parse 报错”除非在 filter 内主动form.emit(error)。错误体系化为多数错误附加code与httpCode详见下文错误码表。大量重命名option.hash→options.hashAlgorithm、file.path→file.filepath、file.type→file.mimetype、file.name拆分为file.newFilename与file.originalFilename。这些字段在 src/PersistentFile.js 与 src/VolatileFile.js 的构造函数中均有体现。默认开启目录遍历防护_joinDirectoryNamesrc/Formidable.js把最终路径path.resolve后与解析过的uploadDir比对若不在uploadDir path.sep前缀之内则回退为defaultInvalidName默认invalid-name从根上杜绝../../型攻击。新增fileWriteStreamHandler自定义落盘目标AWS S3、Azure Blob、GCS 等。_newFile检测到该选项时返回VolatileFilesrc/VolatileFile.js把写入动作完全委托给用户提供的 Writable stream未设置时默认用PersistentFile写本地文件系统。新增allowEmptyFiles、minFileSize字段与文件支持数组接入 Modern Streams API#531引入 Plugins API#545并把 parser 收敛到src/parsers/新增自定义命名options.filename(name, ext, part, form)#591处理无效文件名npm 包不再包含测试文件。插件架构在 src/plugins/multipart.js 中体现得最直观插件接收(formidable, options)其this即 form 实例根据Content-Type匹配后初始化对应 parsermultipart 插件还负责从 header 中抽取 boundary缺失时抛missingMultipartBoundary400 错误。parsers 统一从 src/parsers/index.js 导出JSONParser、MultipartParser、OctetStreamParser、QueryStringParser与DummyParser。v1 时代的历史积累虽然 v1 已废弃CHANGELOG 中的早期条目仍揭示了不少沿用至今的设计v1.2.1maxFileSize选项确立默认 200MB简化 JSON parser 的缓冲逻辑以规避拒绝服务攻击修复请求中止时的上传文件清理修复关闭的_writeStream的错误处理。v1.1.1处理os.tmpDir()弃用警告改用os.tmpdir()并沿用为uploadDir默认值修正buffer.write参数顺序以适配 Node 7JSON parser 向IncomingForm转发 error 事件改进Content-Disposition解析按需在运行时获取fs.WriteStreamhash 写入 JSON。v1.0.14重新启用 hash 计算并补上 hash 测试重排IncomingForm#parse。v1.0.13querystring parser 支持maxKeys控制默认 1000匹配当时 Node 行为空请求处理hash 的 update 方法存在性检查。v1.0.12aborted 连接发 error容忍 multipart 中畸形收尾 boundary忽略 multipart 前导preamble支持application/json、application/octet-stream与 Base64 编码新增File#toJSON文件句柄泄漏修复文档与 benchmark 脚本改进。这些早期决策——流式解析、JSON/octet-stream 支持、hash 计算、临时目录默认值——直到 3.x 仍是库的支柱能力。错误码体系一张表看懂 FormidableError2.0.0 引入的code httpCode错误体系在 src/FormidableError.js 中完整定义。FormidableError继承Error构造参数为(message, internalCode, httpCode 500)。以下是当前仓库3.5.4的全部内部错误码及其典型 httpCodecode常量名典型 httpCode触发场景源码位置1000missingPlugin500enabledPlugins为空src/Formidable.js1001pluginFunction500.use传入非函数src/Formidable.js1002aborted500请求中止src/Formidable.js1003noParser415无匹配 parsersrc/Formidable.js1004uninitializedParser500parser 未初始化即写入src/Formidable.js1005filenameNotString500originalFilename非字符串src/Formidable.js1006maxFieldsSizeExceeded413字段总字节超maxFieldsSizesrc/Formidable.js1007maxFieldsExceeded413字段数量超maxFieldssrc/Formidable.js1008smallerThanMinFileSize400文件小于minFileSizesrc/Formidable.js1009biggerThanTotalMaxFileSize413累计文件字节超maxTotalFileSizesrc/Formidable.js1010noEmptyFiles400allowEmptyFiles: false且文件为空src/Formidable.js1011missingContentType400缺少content-type头src/Formidable.js1012malformedMultipart400multipart 报文畸形/提前结束src/parsers/Multipart.js1013missingMultipartBoundary400multipart 头缺 boundarysrc/plugins/multipart.js1014unknownTransferEncoding501未知传输编码src/plugins/multipart.js1015maxFilesExceeded413文件数量超maxFilessrc/Formidable.js1016biggerThanMaxFileSize413单文件超maxFileSizesrc/Formidable.js1017pluginFailed500插件初始化失败src/Formidable.js3.1.4 补齐1018cannotCreateDir409自动建目录失败src/Formidable.js3.3.2 引入使用时通过import formidable, { errors } from formidable引用这些常量即可在业务层精确区分错误如err.code formidableErrors.maxFieldsExceeded。实战如何把 CHANGELOG 条目对应到源码对于升级排查与二次开发CHANGELOG 源码的对照方法很有价值。以“3.4.0 之后 parse 返回 Promise”为例先在 CHANGELOG 找到条目再到 src/Formidable.js 看parse签名与内部 Promise 分支最后到 test-node/standalone/promise.test.js 看行为断言。仓库还提供了可直接运行的端到端示例examples/with-http.js 展示了createDirsFromUploads、filename、filter、allowEmptyFiles等 3.x 选项的组合用法examples/store-files-on-s3.js 对应fileWriteStreamHandler的流式转发场景。运行测试可使用pnpm run test-node原生 node:test 套件与pnpm run test-jest或一条命令pnpm run test见 package.json。结语纵观 CHANGELOGformidable 的演进呈现出清晰的工程脉络v1 时代确立流式 multipart 解析与 JSON/octet-stream 能力v2 完成 Modern Streams 重写、插件化架构、错误码体系与目录遍历防护v3 走向 ES Modules 与双包发布并以cuid2随机名、maxTotalFileSize限制体系、createDirsFromUploads目录上传等能力补齐安全与体验短板。对于使用者而言本文梳理的 3.2.x 限制选项、3.4.0 Promise API、3.5.x 安全改动与错误码表可直接作为升级到formidablelatest的落地参考。赞分享后端【免费下载链接】formidableThe most used, flexible, fast and streaming parser for multipart form data. Supports uploading to serverless environments, AWS S3, Azure, GCP or the filesystem. Used in production.项目地址https://gitcode.com/gh_mirrors/fo/formidable点击查看免费下载相关推荐GitPython 版本演进与安全加固深度解析从 3.x 变更日志看库的架构演进与防御实践GitPython 版本演进与安全加固深度解析从 3.x 变更日志看库的架构演进与防御实践 GitPython 是一个用于与 Git 仓库交互的 Python版本控制开发工具Paramiko 版本演进全览从 changelog 看 SSHv2 库的安全加固、算法扩展与 API 演进Paramiko 版本演进全览从 changelog 看 SSHv2 库的安全加固、算法扩展与 API 演进 导读 本文以 Paramiko 官方变更日志后端网络通信密码学Spaceship Prompt 版本演进全解析从 4.x 重构到安全加固的 CHANGELOG 深度指南Spaceship Prompt 版本演进全解析从 4.x 重构到安全加固的 CHANGELOG 深度指南 导读 本文以仓库根目录的 CHANGELOG.md开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考