Wagtail API v2无法暴露自定义字段，请求排查原因

可能的原因及对应解决方案 #

1. 属性名拼写错误 #

你代码中写的是api_fileds，正确的属性名应为api_fields（缺少字母e），这是最容易忽略的问题。修正后代码如下：

# Exposing Custom Page Fields/content
api_fields = [
  APIField('content'),
  APIField('custom_title'),
  APIField('blog_image'),
]

2. 未导入APIField类 #

确保在models.py顶部正确导入APIField，否则自定义字段配置不会生效：

from wagtail.api.fields import APIField

3. API默认仅返回基础字段，需显式指定 #

Wagtail API v2默认只返回核心字段（如id、title、meta），自定义字段需要通过以下两种方式之一显式返回：

方式一：请求时携带fields参数

发起API请求时，通过fields参数指定要返回的自定义字段，示例请求地址：

http://localhost/api/v2/pages/32/?fields=title,content,custom_title,blog_image

方式二：自定义视图集设置默认返回字段

如果希望默认返回自定义字段，可在api.py中创建PagesAPIViewSet的子类，扩展默认字段列表：

from wagtail.api.v2.views import PagesAPIViewSet
from wagtail.api.v2.router import WagtailAPIRouter
from wagtail.images.api.v2.views import ImagesAPIViewSet
from wagtail.documents.api.v2.views import DocumentsAPIViewSet

class CustomPagesAPIViewSet(PagesAPIViewSet):
    # 扩展默认字段，添加自定义字段
    default_fields = PagesAPIViewSet.default_fields + ['content', 'custom_title', 'blog_image']

api_router = WagtailAPIRouter('wagtailapi')
# 注册自定义视图集替代默认的PagesAPIViewSet
api_router.register_endpoint('pages', CustomPagesAPIViewSet)
api_router.register_endpoint('images', ImagesAPIViewSet)
api_router.register_endpoint('documents', DocumentsAPIViewSet)

4. 特殊字段需适配序列化规则 #

如果blog_image是Wagtail图片字段，需确保其能被API正确序列化。可以使用ImageRenditionField指定返回的图片格式，示例：

from wagtail.images.api.fields import ImageRenditionField

api_fields = [
  APIField('content'),
  APIField('custom_title'),
  # 返回指定尺寸的图片渲染结果
  ImageRenditionField('blog_image', 'fill-300x200', source='blog_image'),
]

5. 页面未重新发布 #

修改模型的API配置后，需要重新发布对应的AddStory页面，确保页面数据应用最新的API配置规则。

内容的提问来源于stack exchange，提问作者Mohammad Fathi Rahman