老僧博客 半亩方塘,种点代码,也种点生活

记一次百度地图 Web 服务 API 的签名踩坑

前阵子给一个内部小工具接百度地图的逆地理编码服务(把经纬度转成地址),功能本身十分钟就写完了,结果在签名上卡了整整半天。最后发现是一个很不起眼的细节问题,写下来给可能踩同款坑的朋友。

背景

百度地图的 Web 服务 API 有两种鉴权方式:老的 IP 白名单方式和 sk 签名方式。为了安全,我们用的签名方式——请求里带 ak(开发者密钥),再额外带一个 sn 参数。sn 是把请求参数按规则计算出来的校验码,服务端用它来确认请求确实来自你。

正确的计算流程

官方文档里 sn 的计算规则是这样的:

  1. 将所有请求参数(除了 sn 本身)按参数名的字典序排序;
  2. 把排序后的参数用 & 连接成字符串(形如 ak=xxx&callback=xxx&coordtype=xxx...);
  3. 在这个字符串前面拼接请求路径,例如 /geocoding/v3/?ak=xxx&coordtype=...;
  4. 使用 URL 编码(RFC 3986,注意空格要编码成 %20 而不是 +);
  5. 用 UTF-8 编码的字符串与 sk 一起计算 HMAC-SHA1,输出 base64 后再做一次 URL 编码,得到 sn。

看着不复杂对吧?我一开始也是这么想的,结果照着写完,服务端一直返回 AK 校验失败。

坑在哪里

折腾了一下午,最后对着官方调试工具一点一点比对,才发现问题出在编码的时机上。我一开始是先把每个参数值单独做了 URL 编码,再拼起来去算 HMAC——这是错的。正确做法是:先把整个参数字符串原样拼好(不预先编码单个参数),算 HMAC 之前才做统一的 URL 编码。

这俩的区别在于:如果参数值里本身含有 &、=、% 之类的保留字符,先单独编码和最后统一编码得到的字符串不一样,HMAC 自然也就算不对。我们的场景里正好有个参数值带中文(要转成 %E4%B8%AD...),对编码顺序极其敏感。

可用的参考代码

下面是一段可以直接用的 PHP 实现(官方示例里也有,这里按我踩坑后理解的方式重写并加了注释):

<?php
/**
 * 计算百度地图 Web 服务 API 的 sn 签名
 * @param string $url    请求路径,如 /geocoding/v3/
 * @param array  $params 请求参数(不含 sn)
 * @param string $sk     开发者密钥
 */
function baiduSn($url, array $params, $sk) {
    // 1. 按参数名做字典序排序
    ksort($params);

    // 2. 拼成 a=1&b=2 形式的字符串(注意:此时不做 URL 编码)
    $queryStr = http_build_query($params); // PHP 默认 & 分隔,正好是普通 &

    // 3. 前面拼上请求路径,得到待签名串
    $toSign = $url . '?' . $queryStr;

    // 4. 对整串做 RFC 3986 编码(rawurlencode 空格编码为 %20)
    $encoded = rawurlencode($toSign);

    // 5. HMAC-SHA1 → base64 → 再 URL 编码,得到 sn
    $sn = rawurlencode(base64_encode(hash_hmac('sha1', $encoded, $sk, true)));
    return $sn;
}

// 用法示例
$ak    = '你的ak';
$sk    = '你的sk';
$params = [
    'ak'        => $ak,
    'coordtype' => 'wgs84ll',
    'location'  => '39.9042,116.4074', // 样例值
    'output'    => 'json',
];
$url  = '/geocoding/v3/';
$sn   = baiduSn($url, $params, $sk);

// 实际请求
$realUrl = 'https://api.map.baidu.com' . $url
         . '?' . http_build_query($params) . '&sn=' . $sn;

几个容易错的小点顺便提一下:

  • location 参数里的逗号是英文半角逗号,别写成中文的;
  • 调用 URL 和签名时拼接的路径必须一致,/geocoding/v3/ 结尾的斜杠不能省;
  • 如果开了 callback(JSONP 场景),callback 参数也要参与签名,且名字要按字典序排好。

排查建议

如果你也遇到 AK 校验失败,别急着怀疑 ak 本身,先做两件事:一是去百度地图开放平台的 SN 校验工具里把参数粘进去算一遍,看官方工具算出来的 sn 和你的一致不一致;二是把自己拼出来的待签名串打印出来,肉眼对照参数顺序和编码结果。九成的问题,在这两步里都能现形。

半天时间换一个教训:签名类的东西,一定要严格按文档的步骤顺序来,尤其是"编码"和"拼接"的先后次序。望后来者少踩一次坑。

本文为老僧博客原创文章,采用知识共享署名 4.0 国际许可协议(CC BY 4.0)授权。欢迎转载,请注明出处与原文链接。

评论(2)

阿福2025-10-01 16:08
同款坑,我是 Python 里把参数先 quote 了再拼,调了一晚上。这个"编码时机"总结得太到位了。
老周2025-10-03 10:45
SN 校验工具确实是神器,当年也靠它救回来的。博主总结得清楚,收藏了。