在 JavaScript 中编码 Base64：替代已弃用的 btoa 和 atob

问题概述

许多开发者在 VS Code 中遇到了关于 btoa() 和 atob() 函数已被弃用的警告。但需要注意的是，这种弃用仅适用于 Node.js 环境，在浏览器环境中这些函数仍然是标准的 Web API。

核心问题在于：

• btoa() 和 atob() 在 Node.js 中被标记为弃用
• 在浏览器环境中仍然可用，但需要明确使用 window. 前缀
• 需要提供跨环境的替代方案

解决方案

浏览器环境中的使用

在浏览器环境中，btoa 和 atob 仍然是标准的 Web API 的一部分，只需添加 window. 前缀即可消除警告：

// 编码字符串
const encoded = window.btoa('test'); // 返回 "dGVzdA=="

// 解码字符串
const decoded = window.atob('dGVzdA=='); // 返回 "test"

TIP

为什么浏览器中仍然可以使用？ 这些函数是 W3C 标准的一部分，MDN 文档中并未标记为弃用，只是 Node.js 选择了不同的实现方式。

Node.js 环境推荐方案

在 Node.js 环境中，推荐使用 Buffer 类来处理 Base64 编码和解码：

// 编码为 Base64
function encodeBase64(data) {
    return Buffer.from(data).toString('base64');
}

// 从 Base64 解码
function decodeBase64(data) {
    return Buffer.from(data, 'base64').toString('utf8');
}

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

跨平台兼容方案

如果你需要编写在浏览器和 Node.js 中都能运行的代码，可以使用条件判断：

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

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

React 组件中的使用示例

import React from "react";
import { Buffer } from 'buffer';

export default function Base64Example() {
    const encodeBase64 = (data) => {
        return Buffer.from(data).toString('base64');
    }
    
    const decodeBase64 = (data) => {
        return Buffer.from(data, 'base64').toString('utf8');
    }

    return (
        <div>
            <p>编码 'test' 为 Base64: {encodeBase64('test')}</p>
            <p>解码 'dGVzdA==' 为文本: {decodeBase64('dGVzdA==')}</p>
        </div>
    );
}

技术细节

为什么 btoa 在 Node.js 中被弃用？

• btoa() 设计用于处理 8 位字节字符串，无法正确处理 Unicode 字符
• 如果传入包含无法用 8 位表示的字符的字符串，可能会导致错误
• Node.js 的 Buffer API 提供了更强大和一致的二进制数据处理能力

字符编码注意事项

WARNING

重要：确保使用正确的字符编码

当处理非 ASCII 字符时，需要明确指定编码：

// 处理包含 Unicode 的文本
const text = "中文测试";
const encoded = Buffer.from(text, 'utf8').toString('base64');
const decoded = Buffer.from(encoded, 'base64').toString('utf8');

总结

环境	推荐方法	备注
浏览器	window.btoa() / window.atob()	标准 Web API，未弃用
Node.js	Buffer.from().toString('base64')	官方推荐方式
跨平台	条件检测 + 适当回退	确保代码兼容性

INFO

最佳实践建议：对于新项目，建议使用 Buffer API，因为它提供了更好的 Unicode 支持和一致的跨平台行为。

通过采用上述方案，你可以确保代码在现代 JavaScript 环境中正常运行，同时避免弃用警告和潜在的兼容性问题。