npm 包参考
base64hub 是适用于 Node.js 18 及更高版本的 ES 模块,包含四个函数、TypeScript 类型和 b64 命令。没有任何依赖。
安装
npm i base64hub # library
npm i -g base64hub # b64 command
这个包只支持 ESM。用 import 导入;在 CommonJS 中使用 await import("base64hub")。类型定义随包提供。
import { encode, decode, validate, dataUri, Base64Error } from "base64hub";
encode(input, options?)
编码字节或字符串的 UTF-8 字节,返回字符串。input 可以是字符串、Uint8Array(Node.js 的 Buffer 就是一种 Uint8Array)、ArrayBuffer 或任意类型化数组视图。
| 选项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
url | boolean | false | URL 安全字母表(- 和 _)。 |
pad | boolean | true | 添加 = 填充。 |
wrap | number | 0 | 每 N 个字符后插入 \n,结尾不加;76 对应 MIME。 |
encode("Hello, hub!"); // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false }); // "0J_RgNC40LLQtdGC"
encode("foobar", { wrap: 4 }); // "Zm9v\nYmFy"
encode(new Uint8Array([0xfb, 0xff, 0xbf])); // "+/+/"
decode(text)
把 Base64 解码为 Uint8Array。空格、制表符和换行,data:...;base64, 前缀,缺失的填充,以及两种字母表都接受。其他情况会抛出 Base64Error,其 position 是有问题的字符在清理后输入中的索引(从 0 开始)。
decode("+/+/"); // Uint8Array(3) [ 251, 255, 191 ]
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"
try {
decode("Zm9v!");
} catch (e) {
if (e instanceof Base64Error) console.log(e.message, e.position);
// invalid character '!' at position 4 4
}
需要文本时用 new TextDecoder().decode(bytes);其他 Node.js API 需要 Buffer 时用 Buffer.from(bytes)。
validate(text)
检查文本,不抛出异常。恰好在 decode 能成功时有效。
validate("SGVsbG8sIGh1YiE");
// { valid: true, variant: 'either', padded: false, bytes: 11 }
validate("Zm9v!");
// { valid: false, error: "invalid character '!' at position 4" }
| 字段 | 含义 |
|---|---|
valid | true 或 false。 |
variant | standard(出现 + 或 /)、url(出现 - 或 _)、mixed(两者都有)或 either(都没有)。 |
padded | 清理后的长度(含 =)是 4 的倍数。 |
bytes | 解码后的字节数。 |
error | 仅在输入无效时出现:原因,与 decode 抛出的文本相同。 |
dataUri(input, mime?)
生成 data:<mime>;base64,<payload> 字符串:标准字母表,带填充,从不换行。不传 mime 时自动检测类型:PNG、JPEG、GIF、WebP、PDF 和 SVG 按文件签名识别,UTF-8 文本识别为 text/plain;charset=utf-8,其他为 application/octet-stream。
dataUri("Hi"); // "data:text/plain;charset=utf-8;base64,SGk="
dataUri("a,b", "text/csv"); // "data:text/csv;base64,YSxi"
import { readFile } from "node:fs/promises";
dataUri(await readFile("logo.png")); // "data:image/png;base64,iVBORw0KGgo..."
b64 命令
npm i -g base64hub 会安装 b64,npx base64hub "Hello, hub!" 则无需安装即可运行一次。参数、消息和退出码与 CLI 参考 一致。npm 版本会先把全部输入读入内存再处理;非常大的文件请用 Go 版本。
更新于 2026年11月22日