패키지 구성
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 | |
|---|---|---|---|
| 유니코드 텍스트 | 지원 | Latin-1만 | 지원, UTF-8로 처리 |
| URL-safe 알파벳 | "base64url" 인코딩 | 없음 | { url: true }, 디코딩할 때도 허용 |
| 잘못된 문자 | 조용히 건너뜀 | 오류 | 위치를 알려 주는 오류 |
| 검증 | 없음 | 없음 | validate() |
data: URI | 없음 | 없음 | dataUri(), 디코딩할 때는 제거 |
최신 런타임에는 Uint8Array.prototype.toBase64()도 있습니다. 어디서 동작하는지는 이 가이드에서 다룹니다. 패키지 없이 쓰는 Node.js 예제는 Node.js에서 Base64 사용하기를 참고하세요.
여기서 의존성 0개가 중요한 이유
Base64 헬퍼는 토큰, 키, 파일 업로드가 지나가는 길목에 있으므로 긴 의존성 트리를 두기에는 좋지 않은 자리입니다. 이 패키지는 Node.js 내장 모듈만 사용하고, Base64 핵심 코드는 100줄 정도이며, 테스트에서는 CLI, Python 패키지, API도 통과하는 공용 테스트 벡터를 실행합니다.
자주 묻는 질문
npm으로 Base64 CLI를 설치하려면 어떻게 하나요?
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로 인코딩하려면 어떻게 하나요?
바이트를 읽어서 넘기면 됩니다. node:fs/promises의 readFile을 써서 encode(await readFile("logo.png"))처럼 호출합니다. 바로 쓸 수 있는 data:image/png;base64,… 문자열이 필요하면 같은 바이트로 dataUri()를 호출하세요.