使用aws-sdk-js调用compareFaces时触发InvalidParameterException异常

我之前在Node.js环境下用AWS Rekognition的compareFaces时也碰到过这个InvalidParameterException，踩了好几个坑，给你梳理一下最常见的触发原因和对应的解决办法：

1. 图片格式/尺寸/大小不满足要求 #

AWS Rekognition对用于人脸比对的图片有明确限制：

• 支持的格式仅限JPEG、PNG
• 图片像素尺寸至少为40x40，最大不能超过10MB
• 图片不能损坏或包含无效的编码数据

解决办法：

• 先验证图片的格式和完整性，比如用图片查看器打开确认能正常显示
• 如果图片过大，用图片处理库（比如sharp）压缩尺寸或质量：

  const sharp = require('sharp');
  const resizedImageBuffer = await sharp('original.jpg')
    .resize(1200, 1200) // 调整到合适尺寸
    .jpeg({ quality: 80 }) // 压缩质量
    .toBuffer();
  

• 确保图片编码正确，不要传递损坏的文件流或Buffer

2. 图片数据传递方式错误 #

compareFaces支持通过Bytes（本地Buffer）或S3Object（存储在S3的对象）传递图片，两种方式都容易出问题：

• 用Bytes时：可能传递了字符串、未正确读取的文件流，而非标准的Node.js Buffer对象
• 用S3Object时：Bucket名称拼写错误、目标对象不存在、执行请求的IAM角色没有s3:GetObject权限

解决办法：

• 用Bytes传递时，务必用fs.readFileSync或异步读取方法获取标准Buffer：

  const fs = require('fs');
  const sourceImageBytes = fs.readFileSync('./source_face.jpg');
  

• 用S3Object传递时：
  1. 检查Bucket名称和对象Key是否完全匹配（注意大小写，S3 Bucket名称是小写的）
  2. 确认IAM角色已配置rekognition:CompareFaces和s3:GetObject权限
  3. 测试能否通过AWS CLI直接获取该S3对象：aws s3 cp s3://your-bucket/target_face.jpg ./test.jpg

3. 参数值超出合法范围 #

最容易忽略的是SimilarityThreshold参数，它要求是0到100之间的数值（整数或浮点数），如果传了负数、大于100的数，或者非数值类型，都会触发参数错误。

解决办法：

• 检查请求参数中的SimilarityThreshold，确保它在0-100范围内，比如：

  const params = {
    SourceImage: { Bytes: sourceImageBytes },
    TargetImage: { Bytes: targetImageBytes },
    SimilarityThreshold: 85 // 合法范围：0 ≤ 值 ≤ 100
  };
  

4. 请求参数结构不规范 #

拼写错误或者参数嵌套结构不对也会导致这个异常，比如把SourceImage写成SourceImg，或者S3Object里的键名写成BucketName而非Bucket。

解决办法：

• 对照AWS官方文档的参数结构，检查你的请求对象：

  // 正确的参数结构示例
  const params = {
    SourceImage: {
      Bytes: Buffer.from('...') // 或 S3Object: { Bucket: 'xxx', Name: 'xxx' }
    },
    TargetImage: {
      Bytes: Buffer.from('...') // 或 S3Object: { Bucket: 'xxx', Name: 'xxx' }
    },
    SimilarityThreshold: 70
  };
  

5. 图片中未检测到人脸 #

有时候Rekognition无法从Source或Target图片中识别出人脸，也会把这个错误归类为参数无效（部分场景下错误信息会更明确，但偶尔会统一抛出InvalidParameterException）。

解决办法：

• 先单独用detectFaces接口测试图片是否能检测到人脸：

  const detectParams = { Image: { Bytes: testImageBytes } };
  rekognition.detectFaces(detectParams, (err, data) => {
    if (err) console.log(err, err.stack);
    else console.log('检测到的人脸数量:', data.FaceDetails.length);
  });
  

• 确保图片中的人脸清晰、无严重遮挡，光线充足，人脸占据图片的比例不要过小

开启AWS SDK的调试日志，可以看到实际发送的请求参数，更容易定位问题：

const AWS = require('aws-sdk');
AWS.config.logger = console; // 打印所有SDK请求日志

内容的提问来源于stack exchange，提问作者Keith Darragh