上传文件
  1. base64hub
  2. 文档
  3. npm 包

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 或任意类型化数组视图。

选项类型默认值作用
urlbooleanfalseURL 安全字母表(- 和 _)。
padbooleantrue添加 = 填充。
wrapnumber0每 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" }
字段含义
validtrue 或 false。
variantstandard(出现 + 或 /)、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日