Agora云录制API出现‘fileNamePrefix validation failed’错误求助

核心问题分析 #

Agora Cloud Recording API v1对fileNamePrefix的验证严格遵循字符规则与存储服务兼容要求，失败根源基本集中在以下几点：

• 数组元素包含违规字符（如空格、中文、特殊符号）
• 单个元素长度超过64字符限制
• 存在空字符串元素
• 不符合AWS S3对象键的命名规范

具体修复步骤 #

1. 清洗动态字段的违规字符 #

确保channel_name和user_id只保留允许的字符（字母、数字、下划线_、连字符-、点.）：

// 过滤动态值中的违规字符
const cleanChannelName = channel_name.replace(/[^a-zA-Z0-9_\-\.]/g, '');
const cleanUserId = user_id.toString().replace(/[^a-zA-Z0-9_\-\.]/g, '');

const start_recording_payoad = {
  "uid": user_id.toString(),
  "cname": channel_name,
  "clientRequest": {
    "token": token,
    "recordingConfig": {
      "maxIdleTime": 30,
      "streamTypes": 2,
      "channelType": 0,
      "videoStreamType": 0,
      "transcodingConfig": {
        "height": 720,
        "width": 1280,
        "bitrate": 2000,
        "fps": 30,
        "mixedVideoLayout": 1,
        "backgroundColor": "#000000"
      }
    },
    "recordingFileConfig": {
      "avFileType": ["hls", "mp4"]
    },
    "storageConfig": {
      "accessKey": "xxxxxxxx",
      "region": 9,
      "bucket": "xxxxxx",
      "secretKey": "SECRET_KEY_HIDDEN",
      "vendor": 2,
      "fileNamePrefix": ["partner_live_stream_recording", cleanChannelName, cleanUserId]
    }
  }
};

2. 限制元素长度 #

单个fileNamePrefix元素不能超过64字符，对过长字段做截断处理：

const safeChannelName = cleanChannelName.slice(0, 64);
const safeUserId = cleanUserId.slice(0, 64);

3. 避免空字符串元素 #

为动态值添加默认值，防止出现空字符串：

const finalChannelName = safeChannelName || 'default_channel';
const finalUserId = safeUserId || 'default_user';

4. 用静态合法配置做基准测试 #

先使用完全合规的静态数组测试API是否能正常启动，排除其他字段干扰：

"fileNamePrefix": ["test_recording", "channel_001", "user_123"]

如果该配置能成功，说明问题出在动态值的格式上，再逐步替换回真实值排查。

5. 确认AWS S3兼容性 #

• 已设置的region:9确实对应ap-south-1（符合Agora文档规范）
• 确保AWS密钥拥有S3的PutObject权限，存储桶无特殊访问限制

额外注意事项 #

• Agora会自动在fileNamePrefix元素间添加斜杠/，无需手动添加
• 不要在fileNamePrefix中包含文件扩展名，Agora会根据avFileType自动生成

内容的提问来源于stack exchange，提问作者suraj karosia