JavaScriptにおけるBase64エンコード/デコードの完全ガイド

問題点

最近、Visual Studio Codeで作業していると、btoa() と atob() 関数が非推奨（deprecated）であるという警告が表示されるようになりました。これらの関数はJavaScriptでBase64エンコードとデコードを行う従来の方法でしたが、最新の開発環境では推奨されなくなりました。

非推奨警告の意味

非推奨警告は、将来的にその機能がサポートされなくなる可能性があることを示しています。新しいコードでは代替手段を使用することが推奨されます。

解決策

ブラウザ環境での解決策

ブラウザ環境では、btoa() と atob() は実際には非推奨ではなく、window オブジェクトを通じて引き続き使用できます。

// エンコード
const encoded = window.btoa('test'); // "dGVzdA=="

// デコード
const decoded = window.atob('dGVzdA=='); // "test"

ブラウザ環境での注意点

• btoa() は8ビットバイトで表現できない文字を含む文字列を処理すると問題が発生します
• 日本語などのマルチバイト文字を扱う場合は、適切なエンコード処理が必要です

Node.js環境での解決策

Node.js環境では、Buffer クラスを使用するのが推奨される方法です。

// エンコード
const encodeBase64 = (data) => {
    return Buffer.from(data).toString('base64');
};

// デコード
const decodeBase64 = (data) => {
    return Buffer.from(data, 'base64').toString('utf8');
};

// 使用例
const encoded = encodeBase64('test'); // "dGVzdA=="
const decoded = decodeBase64('dGVzdA=='); // "test"

クロスプラットフォーム対応の方法

ブラウザとNode.jsの両方で動作するコードが必要な場合は、以下のような方法があります。

方法1: 環境判別による実装

const encodeBase64 = (data) => {
    if (typeof window !== 'undefined' && window.btoa) {
        return window.btoa(data);
    } else if (typeof Buffer !== 'undefined') {
        return Buffer.from(data).toString('base64');
    }
    throw new Error('Base64 encoding not supported');
};

const decodeBase64 = (data) => {
    if (typeof window !== 'undefined' && window.atob) {
        return window.atob(data);
    } else if (typeof Buffer !== 'undefined') {
        return Buffer.from(data, 'base64').toString('utf8');
    }
    throw new Error('Base64 decoding not supported');
};

方法2: bufferパッケージの使用（ブラウザ用）

// npm install buffer または yarn add buffer
import { Buffer } from 'buffer';

const encodeBase64 = (data) => {
    return Buffer.from(data).toString('base64');
};

const decodeBase64 = (data) => {
    return Buffer.from(data, 'base64').toString('utf8');
};

詳細な解説

なぜ btoa/atob は非推奨と表示されるのか

TypeScriptや一部の開発環境では、Node.js環境での btoa と atob の使用が非推奨とマークされています。これは以下の理由によります：

• Node.jsのグローバルスコープにあるこれらの関数は、本来ブラウザ用のAPIです
• Node.jsでは Buffer クラスがより効率的で一貫性のあるAPIを提供します
• 文字エンコードの問題（特に8ビット以外の文字の処理）を回避できます

文字エンコードの問題と解決策

btoa() はASCII文字列（各文字が8ビットバイト）を期待します。日本語などのUTF-8文字列を処理する場合は、適切なエンコード処理が必要です。

// UTF-8文字列を安全にエンコードする方法
const encodeUTF8Base64 = (str) => {
    if (typeof window !== 'undefined') {
        // ブラウザ環境
        const bytes = new TextEncoder().encode(str);
        const binary = bytes.reduce((acc, byte) => acc + String.fromCharCode(byte), '');
        return window.btoa(binary);
    } else {
        // Node.js環境
        return Buffer.from(str, 'utf8').toString('base64');
    }
};

// デコード
const decodeUTF8Base64 = (base64) => {
    if (typeof window !== 'undefined') {
        // ブラウザ環境
        const binary = window.atob(base64);
        const bytes = new Uint8Array(binary.length);
        for (let i = 0; i < binary.length; i++) {
            bytes[i] = binary.charCodeAt(i);
        }
        return new TextDecoder().decode(bytes);
    } else {
        // Node.js環境
        return Buffer.from(base64, 'base64').toString('utf8');
    }
};

まとめ

環境に応じたBase64エンコード/デコードの推奨方法：

環境	推奨方法
ブラウザ	window.btoa() / window.atob()
Node.js	Buffer.from().toString('base64') / Buffer.from(data, 'base64').toString('utf8')
ユニバーサル（クロスプラットフォーム）	環境判別またはbufferパッケージ

重要

常に対象となる実行環境を考慮し、適切な方法を選択してください。日本語などのマルチバイト文字を扱う場合は、文字エンコードに特に注意が必要です。

最新のJavaScriptプロジェクトでは、Buffer APIを使用することを推奨します。これはNode.js環境でネイティブにサポートされ、ブラウザではbufferパッケージを介して使用できるため、コードの一貫性を保つのに役立ちます。