safer-buffer

中文文档
2.1.2发布于 2018/04/08MITCommonJS零依赖近 30 天下载 8亿

现代缓冲API填充没有脚枪

中文使用文档
文档目录7 节
  1. 如何使用?
  2. 我需要它吗?
  3. 为什么不 safe-buffer ?
  4. 但是投掷不是坏事吗?
  5. 它会影响第三方模块吗?
  6. 但我不想扔……
  7. «没有footguns»吗?

safer-buffer travis npm javascript style guide Security Responsible Disclosure

没有脚炮的现代Buffer API polyfill,从0.8到现在在Node.js上工作。

如何使用?

首先,所有端口 Buffer() 和 new Buffer() 调用 Buffer.alloc() 和 Buffer.from() API。

然后,为了与过时的Node.js版本兼容(<4.5.0 和5.倍 <5.9.0),使用 const Buffer = require('safer-buffer').Buffer 在所有你打电话给新 缓冲API。 使用 var 而不是 const 如果你需要你的Node.js版本范围支持。

另外,请参阅 移植缓冲 指南。

我需要它吗?

希望不要放弃对过时的Node.js版本的支持,现在应该没问题了 是推荐的前进路径。你 做。 需要移植到 Buffer.alloc() 和 Buffer.from() 虽然。

看到 移植指南 为了更好的描述。

为什么不 safe-buffer?

简而言之: safe-buffer 作为新API的填充,它允许旧API的使用和 它本身就有步兵枪。

safe-buffer 可以安全地使用新API,同时仍然保持对旧API的支持 Node.js版本(像这个模块),但同时分析旧Buffer API的生态系统使用情况 我发现 safe-buffer 它本身在某些情况下会引起问题。

例如,考虑下面的代码片段:

$ cat example.unsafe.js
console.log(Buffer(20))
$ ./node-v6.13.0-linux-x64/bin/node example.unsafe.js
<Buffer 0a 00 00 00 00 00 00 00 28 13 de 02 00 00 00 00 05 00 00 00>
$ standard example.unsafe.js
standard: Use JavaScript Standard Style (https://standardjs.com)
  /home/chalker/repo/safer-buffer/example.unsafe.js:2:13: 'Buffer()' was deprecated since v6. Use 'Buffer.alloc()' or 'Buffer.from()' (use 'https://www.npmjs.com/package/safe-buffer' for '<4.5.0') instead.

这是分配和写入控制台一个未初始化的内存块。 标准 Linter(以及其他人)发现了这一点并警告人们 以避免使用不安全的API。

现在让我们加入进来 safe-buffer!

$ cat example.safe-buffer.js
const Buffer = require('safe-buffer').Buffer
console.log(Buffer(20))
$ standard example.safe-buffer.js
$ ./node-v6.13.0-linux-x64/bin/node example.safe-buffer.js
<Buffer 08 00 00 00 00 00 00 00 28 58 01 82 fe 7f 00 00 00 00 00 00>

看到问题了吗?添加在 safe-buffer 神奇地去除绒毛警告,但是行为 与我们之前在Node.js 6上发布时一样。x LTS -这转储 未初始化的内存块。 这段代码仍然会在Node.js 10上发出运行时警告。X及以上。

这是设计出来的。我开始考虑改变 safe-buffer,禁止使用旧的API或 发出警告,但这与 safe-buffer 设计。在一些 经过讨论,我们决定把我的方法放到一个单独的包里 这是分开的 包。

这个足球枪不是想象出来的——我观察过下载量最高的软件包会做这样的事情, 通过盲目地包含“修复”绒毛警告 safe-buffer 没有任何实际的改变。

在某些情况下,即使API 是 迁移到使用安全的Buffer API -随机拉取请求 可以通过添加新调用将不安全的Buffer API使用带回代码库-这可能会消失吗 即使你有一个禁止这样做的衬垫,也不会被注意到(因为上面提到的原因),甚至 通过CI。 我还观察到,在流行的软件包中也有这样做。

一些例子:

我提交了一份公共关系申请 mysticatea / eslint-plugin-node # 110 来 部分修复了这个问题(对于使用lint规则的情况),但是对于 过滤规则和预设,所以需要很长时间才能达到实际设置。 也尚未发布(2018-03-20)。

同时, safer-buffer 不鼓励使用 .allocUnsafe()这通常是由错误造成的。 它仍然通过显式的关注屏障来支持它,通过将其置于 require('safer-buffer/dangereous')。

但是投掷不是坏事吗?

不是真的。这是一个可以及早发现和修复的错误,而不是像 无防备的 new Buffer() 最终接收用户输入的调用可以做。

此包仅影响以下文件 var Buffer = require('safer-buffer').Buffer 完成了,所以 跟踪事物并确保你没有将旧API的使用与之混合是非常简单的。 此外,CI应该提示您可能错过的任何内容。

如果经过测试,新的提交不会以这种方式使用不安全的Buffer API。 node . js 10。X还通过打印运行时耗尽警告来处理这个问题。

它会影响第三方模块吗?

不,除非你显式地做了一件可怕的事情,比如猴子补丁或重写内置 Buffer。 不要那样做。

但我不想扔……

这也很好!

此外,在某些情况下,当您没有足够全面的测试覆盖时,它可能会更好。

在这种情况下,不要重写 Buffer 和使用 var SaferBuffer = require('safer-buffer').Buffer 代替。

这样,一切都用上了 Buffer 原生的仍然可以工作,但会有两个缺点:

  • Buffer.from/Buffer.alloc 不会被填充-使用 SaferBuffer.from 和 SaferBuffer.alloc 代替。
  • 您仍然有可能意外使用不安全的已弃用API -使用过滤器来捕获它。

注意使用过滤器捕捉意外 Buffer 在这种情况下,构造函数的使用是强的 推荐。 Buffer 在这个用例中没有被重写,所以lint不会混淆。

«没有footguns»吗?

嗯,还是有可能做到的 一些 的东西 Buffer API,例如 .buffer 财产 在旧版本上进行复制。你可能不应该在你的代码中这么做。

这样做的目的是为了移除那些影响大量软件包的最重要的漏洞 生态系统,并以正确的方式做到这一点。

此外,这个包不能防止影响某些Node.js版本的安全问题,所以for 在您自己的生产代码中使用,仍然建议更新到Node.js版本 上游支持。

版本与发布记录

safer-buffer 共发布 7 个版本,首次发布于 2018/03/19;过去 12 个月发布了 0 个版本。

版本发布日期距今
2.1.2latest2018/04/088 年前
2.1.12018/04/088 年前
2.1.02018/03/228 年前
2.0.22018/03/208 年前
2.0.12018/03/198 年前
2.0.02018/03/198 年前

关于 safer-buffer 的常见问题

safer-buffer 是什么?

现代缓冲API填充没有脚枪

如何安装 safer-buffer?

在项目目录运行 npm install safer-buffer,或使用 pnpm add / yarn add / bun add。

safer-buffer 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/safer-buffer 是否存在。

safer-buffer 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

safer-buffer 可以商用吗?

safer-buffer 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

safer-buffer 的下载量有多少?

根据 npm 官方下载统计,safer-buffer 在 2026/10/07 – 2026/11/05 这 30 天内被下载 797,174,056 次,日均约 26,572,469 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

safer-buffer 还在维护吗?

最新版本 2.1.2 发布于 2018/04/08(8 年前);至今共发布 7 个版本,其中过去 12 个月发布了 0 个;首次发布于 2018/03/19。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。