包里有什么
base64hub 是一个 ES 模块,包含四个函数,没有任何依赖。它可在 Node.js 18 及更高版本上运行。
| 函数 | 返回值 |
|---|---|
encode(bytesOrString, { url, pad, wrap }) | Base64 文本;字符串会先编码为 UTF-8 |
decode(string) | 一个 Uint8Array;输入无效时抛出异常 |
validate(string) | { valid, variant, padded, bytes },或 { valid: false, error } |
dataUri(bytes, mime?) | 一个 data: URI;省略 MIME 类型时自动检测 |
npm i base64hub
import { encode, decode, validate, dataUri } from "base64hub";
encode("Hello, hub!"); // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false }); // "0J_RgNC40LLQtdGC"
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"
validate("-_-_").variant; // "url"
dataUri(new TextEncoder().encode("Hi")); // "data:text/plain;charset=utf-8;base64,SGk="
decode 接受人们实际会粘贴的各种内容:换行、空格、缺失的 = 填充、data:...;base64, 前缀,以及两种字母表。除此之外的一律拒绝,例如多出来的 !、中间的 =,或者根本不可能是 Base64 的长度。
通过 npm 获取 b64 命令
全局安装会添加 b64 命令,它与 原生 CLI 是同一个工具,参数和退出码也相同:
$ npm i -g base64hub
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!
npm 版本会先把全部输入读入内存再处理。几 GB 的文件请用支持流式处理的 Go 版本。npm 文档 列出了所有选项。
base64hub 与 Buffer、btoa 和 atob 对比
Node.js 已经内置了 Base64,处理可信数据时完全够用。差别体现在并非你自己生成的输入上。下面几行在 Node.js 24 上实际运行过:
Buffer.from("Zm9v!YmFy", "base64").toString(); // "foobar", the "!" is skipped silently
btoa("Привет"); // throws InvalidCharacterError (Latin-1 only)
atob("-_-_"); // throws InvalidCharacterError (no URL-safe)
Buffer | btoa / atob | base64hub | |
|---|---|---|---|
| Unicode 文本 | 支持 | 仅限 Latin-1 | 支持,按 UTF-8 处理 |
| URL 安全字母表 | "base64url" 编码 | 不支持 | { url: true },解码时也接受 |
| 无效字符 | 静默跳过 | 报错 | 报错并给出位置 |
| 校验 | 不支持 | 不支持 | validate() |
data: URI | 不支持 | 不支持 | dataUri(),解码时自动去掉前缀 |
较新的运行时还新增了 Uint8Array.prototype.toBase64();这篇指南 介绍了它在哪些环境中可用。更多不依赖任何包的 Node.js 代码片段,见 Node.js 中的 Base64。
为什么零依赖在这里很重要
Base64 辅助函数处在令牌、密钥和文件上传的必经之路上,这种地方不适合挂一长串依赖。这个包只使用 Node.js 内置模块,Base64 核心代码大约一百行,测试运行的是一套共享的测试向量,CLI、Python 包和 API 也都通过了这套测试。
常见问题
怎样用 npm 安装 Base64 命令行工具?
npm i -g base64hub 会全局安装 b64 命令。不想安装、只想试一次,可以运行 npx base64hub "Hello, hub!"。
base64hub 包能用 require() 加载吗?
它是 ES 模块,请用 import { encode } from "base64hub" 加载。在 CommonJS 文件中,使用动态的 await import("base64hub")。
Node.js 已经有 Buffer,为什么还要用这个包?
Buffer.from(text, "base64") 会跳过它不认识的字符,损坏的输入就这样变成了错误的字节,却不报任何错。base64hub 的 decode() 会拒绝这类输入并报告位置,validate() 则在解码之前告诉你字母表和大小。
怎样用 base64hub 在 Node.js 中把文件编码为 Base64?
读取字节后传进去:encode(await readFile("logo.png")),其中 readFile 来自 node:fs/promises。想要现成的 data:image/png;base64,… 字符串,就对同样的字节调用 dataUri()。