Wagtail 2.0.1对接AWS S3：图片正常，上传后文档不显示

看起来你遇到的问题是Wagtail文档模块能正常上传文件到S3，但后台列表和搜索结果无法正确展示内容——这在自定义存储后端的场景下很常见，尤其是Wagtail 2.x这类相对早期的版本，文档模块有几个容易被忽略的配置点：

1. 配置Wagtail文档专属的存储后端 #

Wagtail的图片模块会直接使用DEFAULT_FILE_STORAGE，但文档模块在2.x版本中支持单独配置存储后端。你需要在settings中添加专门针对文档的存储配置：

# 针对Wagtail文档模块设置S3存储
WAGTAILDOCS_STORAGE = 'filebrowser_s3.storage.S3MediaStorage'

这个配置会让Wagtail的文档模型明确使用你的S3存储类，而不是依赖默认的存储设置（虽然理论上默认会用DEFAULT_FILE_STORAGE，但显式配置能避免版本兼容问题）。

2. 检查存储类的核心方法实现 #

你的filebrowser_s3.storage.S3MediaStorage是基于S3Boto3Storage扩展的，需要确保它正确实现了Wagtail文档模块依赖的几个方法：

• url()：必须返回可访问的S3文件URL，要确保拼接了AWS_S3_CUSTOM_DOMAIN和正确的文件路径，没有遗漏AWS_LOCATION前缀；
• exists()：Wagtail在渲染列表时会检查文件是否存在，如果这个方法返回False，即使数据库有记录，也不会显示在列表中；
• size()：文档列表需要显示文件大小，如果这个方法无法正确获取S3文件的大小，也可能导致前端不渲染条目。

3. 验证数据库记录与S3路径的一致性 #

检查数据库中wagtaildocs_document表的file字段值，确保它和S3上的实际文件路径完全匹配：

• 比如如果你的AWS_LOCATION设置了media/docs，那么数据库中的file字段应该是media/docs/your-document.pdf，而不是your-document.pdf；
• 如果存储类自动添加了前缀，但Wagtail的文档模型没有正确处理，就会导致路径不匹配，无法加载文件信息。

4. 检查缓存与路由有效性 #

尝试清除Wagtail的缓存（包括浏览器缓存、Django的服务器缓存），或者重启服务，确保路由配置没有被缓存影响。另外，确认wagtail.documents已经正确添加到INSTALLED_APPS中（不过既然能完成上传操作，这一步大概率已经配置好了）。

按照这几个步骤排查后，应该能解决文档列表不显示的问题。

内容的提问来源于stack exchange，提问作者Mike 'Pomax' Kamermans