====== base64url ======
**base64url 就是 Base64 的“URL 安全”版本**(RFC 4648 §5)。字母表沿用标准 Base64,只把两个会惹麻烦的符号换掉,并约定可以省略尾部的等号填充,于是它能直接出现在 URL、文件名、Cookie、JWT 这类场景里而无需再转义。
^ 特征 ^ 标准 Base64 ^ base64url ^
| 第 62 个字符 | ''+'' | ''-'' |
| 第 63 个字符 | ''/'' | ''_'' |
| 尾部填充 | ''='' | 省略 |
| 规范 | RFC 4648 §4 | RFC 4648 §5 |
| 能否直接放进 URL | 需要额外转义 | 可以 |
===== 为什么需要它 =====
标准 Base64 的字母表里有三个字符在 URL / 表单上下文里是保留字符:
* ''+'':在 ''application/x-www-form-urlencoded'' 里会被解码成空格,数据被悄悄破坏。
* ''/'':URL 的路径分隔符,放进 path 段会改变路由语义。
* ''='':query string 里用于分隔参数名和值,拼接时容易出错;部分框架或网关还会吃掉尾部的 ''=''。
RFC 4648 因此定义了 base64url:换成 ''-'' 和 ''_'',并约定尾部 ''='' 可以省略(因为长度对 4 取模就能推断出该补几个填充)。
===== 字母表 =====
* 标准 Base64:''A-Z'' ''a-z'' ''0-9'' ''+'' ''/''
* base64url:''A-Z'' ''a-z'' ''0-9'' ''-'' ''_''
前 62 个字符完全相同,只有后两个换掉了。也就是说,**只有当原始数据恰好编码出 ''+'' 或 ''/'' 时,两者才有差别**,所以单纯做字母表替换是安全且可逆的。
===== 编码原理 =====
- 每 3 个字节(24 bit)分为一组
- 把 24 bit 切成 4 个 6 bit 值(取值 0~63)
- 用字母表把每个值映射成一个字符
- 不足 3 字节时低位补 0 凑满,最后输出 ''='' 填充(base64url 可省略填充)
以两个字节 ''0xFB 0xFF'' 为例:
原始: 1111 1011 1111 1111 (16 bit)
补 0: 1111 1011 1111 1111 0000 0000 (凑成 24 bit)
切分: 111110 111111 110000 000000
数值: 62 63 60 0
字符: + / 8 = ← 标准 Base64
- _ 8 ← base64url(省略尾部填充)
===== 长度怎么算 =====
去掉填充后,长度不再一定是 4 的倍数:
^ 原始字节 n ^ 标准 Base64(含 ''='') ^ base64url(去填充) ^
| 1 | 4 | 2 |
| 2 | 4 | 3 |
| 3 | 4 | 4 |
| 4 | 8 | 6 |
| 5 | 8 | 7 |
| n | 4×⌈n/3⌉ | ⌈4n/3⌉ |
===== 各语言怎么写 =====
== Python ==
Python 的 ''urlsafe_b64encode'' 只换字母表、**不**去填充,需要自己 ''rstrip'':
import base64
raw = b"\xfb\xff"
base64.b64encode(raw).decode() # '+/8=' 标准
base64.urlsafe_b64encode(raw).decode() # '-_8=' base64url(仍带填充)
def b64url_encode(b: bytes) -> str:
return base64.urlsafe_b64encode(b).decode().rstrip("=")
def b64url_decode(s: str) -> bytes:
s += "=" * (-len(s) % 4) # 补齐到 4 的倍数
return base64.urlsafe_b64decode(s.encode())
== JavaScript / Node ==
// Node 14.18+ / 现代浏览器
Buffer.from([0xfb, 0xff]).toString('base64'); // '+/8='
Buffer.from([0xfb, 0xff]).toString('base64url'); // '-_8'
// 浏览器里没有 base64url 时手动替换
const b64url = (bytes) => btoa(String.fromCharCode(...bytes))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
== Java ==
String s = Base64.getUrlEncoder()
.withoutPadding()
.encodeToString(new byte[]{(byte) 0xfb, (byte) 0xff}); // -_8
byte[] b = Base64.getUrlDecoder().decode(s);
== Go ==
enc := base64.RawURLEncoding // Raw = 无填充的 URL 安全变体
s := enc.EncodeToString([]byte{0xfb, 0xff}) // "-_8"
b, err := enc.DecodeString(s)
== C# / .NET ==
using Microsoft.AspNetCore.WebUtilities;
var s = WebEncoders.Base64UrlEncode(new byte[] { 0xfb, 0xff }); // -_8
var b = WebEncoders.Base64UrlDecode(s);
===== 典型使用场景 =====
* **JWT**:''header.payload.signature'' 三段全部是 base64url,且**不带** ''='' 填充(RFC 7515)。
* **JWK**:''n''、''e''、''k'' 等参数值都用 base64url 表示。
* **OAuth 2.0 PKCE**:''code_verifier'' / ''code_challenge'' 要求 base64url 无填充(RFC 7636)。
* **在 URL 中携带二进制**:nonce、密文串、protobuf 序列化结果、签名。
* **文件名 / Cookie / 短链 token**:避免 ''+'' 被解码成空格、''/'' 被当成路径。
* **展示摘要或指纹**:SPKI pin、GraphQL 的 opaque ID 等。
===== 常见坑 =====
- **填充不一致**。JWT 用的是严格无填充版本;自己编码要 %%rstrip('=')%%,自己解码要先补齐 %%'='%%。
- **解码器不能混用**。多数 base64url 解码器能容忍 ''+'' ''/'',但标准解码器遇到 ''-'' ''_'' 会直接报错。
- **它不是加密,也不是压缩**。只是可逆编码,体积还会涨约 33%(换成 hex 则涨 100%)。
- **大小写敏感**。不要做 ''toLowerCase()'' 之类的归一化,''A'' 和 ''a'' 是两个不同的值。
- **替换方向要成对**。编码时 ''+''→''-''、''/''→''_'',解码时严格反向,只改一边就会出现“有时正常有时报错”的 bug。
- **去填充后长度不再对齐 4**。按 4 字符分块做分段编码或分块传输时要单独处理。
===== 与其他编码对比 =====
^ 编码 ^ 体积变化 ^ 可直接放进 URL ^ 说明 ^
| Hex | +100% | 是 | 最简单、体积最差 |
| 标准 Base64 | +33% | 否(''+'' ''/'' ''='') | 通用二进制转文本 |
| base64url | +33% | 是 | URL / JWT 场景首选 |
| Base32 | +60% | 是 | 可人工朗读、常做不区分大小写场景 |
===== 一图总览 =====
```mdk height=420 color=#0ea5e9
# base64url
## 是什么
- Base64 的 URL 安全变体(RFC 4648 §5)
- 字母表:A-Z a-z 0-9 - _
- 尾部 = 填充可省略
## 为什么要有它
- + 在表单里被解码成空格
- / 是 URL 路径分隔符
- = 是 key=value 分隔符
## 编码原理
- 3 字节 → 4 个 6bit → 查表
- 不足 3 字节低位补 0
- 长度 = ⌈4n/3⌉(去填充)
## 用在哪
- JWT / JWK
- OAuth PKCE
- URL 里的二进制、token
- 文件名 / Cookie
## 注意事项
- 填充必须前后一致
- 标准与 url 解码器别混用
- 不是加密,体积涨 33%
- 大小写敏感
```