如何为PDF中/figure标签图片添加ALT文本以符合WCAG 2.1 AA并适配AWS Lambda

方案1：修正pikepdf操作流程（可靠且轻量） #

之前用pikepdf导致文件损坏，大概率是没正确处理PDF的结构树和交叉引用。以下是正确操作步骤：

1. 定位Adobe标记的Figure结构元素
   Adobe自动标记的/figure对应PDF结构树中/Type /StructElem且/S /Figure的节点，需遍历结构树找到这些节点。

2. 给结构元素添加ALT文本
   给目标StructElem字典添加/Alt条目，值为包含ALT文本的PDF字符串对象。

3. 正确保存PDF
   使用pikepdf的save()方法时，保留原有PDF的所有结构，避免破坏交叉引用表。

Lambda适配代码示例 #

import pikepdf
from pikepdf import Dictionary, Name, String

def add_alt_text_to_figures(input_pdf_bytes, alt_text_mapping):
    # alt_text_mapping：键为Figure元素标识（如序号/自定义ID），值为对应ALT文本
    with pikepdf.open(input_pdf_bytes) as pdf:
        if Name.MarkInfo not in pdf.root or Name.StructTreeRoot not in pdf.root:
            raise ValueError("PDF未包含Adobe自动标记的结构树")
        
        struct_root = pdf.root[Name.StructTreeRoot]
        
        # 递归遍历结构树查找Figure节点
        def traverse_struct_elem(elem, elem_id=0):
            if elem[Name.S] == Name.Figure:
                alt_text = alt_text_mapping.get(str(elem_id), "")
                if alt_text:
                    elem[Name.Alt] = String(alt_text)
            if Name.K in elem:
                kids = elem[Name.K]
                if isinstance(kids, list):
                    for idx, kid in enumerate(kids):
                        if isinstance(kid, Dictionary) and kid.get(Name.Type) == Name.StructElem:
                            traverse_struct_elem(kid, elem_id + 1)
        
        traverse_struct_elem(struct_root[Name.K])
        output_bytes = pdf.save_to_bytes()
        return output_bytes

def lambda_handler(event, context):
    import boto3
    s3 = boto3.client('s3')
    input_bucket = event['input_bucket']
    input_key = event['input_key']
    output_bucket = event['output_bucket']
    output_key = event['output_key']
    
    # 从事件参数读取ALT文本映射，也可从数据库/配置中心获取
    alt_text_mapping = event['alt_text_mapping']
    
    # 获取PDF字节流
    response = s3.get_object(Bucket=input_bucket, Key=input_key)
    input_pdf_bytes = response['Body'].read()
    
    # 添加ALT文本
    output_pdf_bytes = add_alt_text_to_figures(input_pdf_bytes, alt_text_mapping)
    
    # 上传处理后的PDF到S3
    s3.put_object(Bucket=output_bucket, Key=output_key, Body=output_pdf_bytes)
    
    return {
        'statusCode': 200,
        'output_key': output_key
    }

Lambda部署注意事项 #

• 将pikepdf及其依赖打包成Lambda层：在本地创建虚拟环境，安装pikepdf后把site-packages目录打包成zip，上传为Lambda层。
• 配置Lambda内存至少256MB，超时时间根据PDF大小调整（建议10-30秒）。

方案2：使用Adobe PDF Services API（企业级无代码维护） #

如果不想维护开源库兼容性，可使用Adobe官方的PDF Services API，它支持给已标记的Figure元素添加ALT文本，完全符合WCAG标准。

Lambda集成要点 #

• 在Lambda中调用API的addAltText接口，传入PDF文件和ALT文本映射。
• 配置Adobe API凭证（API密钥+私钥）到Lambda环境变量中。
• 优势：无需处理PDF底层结构，彻底避免文件损坏风险，官方维护兼容性。

常见问题排查 #

• 文件损坏：只操作结构树中的StructElem对象，不要直接修改页面内容；使用库原生保存方法，禁止手动修改PDF字节。
• 找不到Figure节点：确认PDF已被Adobe正确标记，检查根字典中是否存在/MarkInfo和/StructTreeRoot。
• Lambda环境异常：依赖库需适配Amazon Linux 2环境，避免使用编译时依赖不兼容的包。

内容的提问来源于stack exchange，提问作者Aryan Khanna