Wagtail 2.8 版本发布全解析Django 3.0 支持、独占式页面锁定与 API 端点迁移指南【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail导读本文基于 Wagtail 官方 2.8 版本发布说明docs/releases/2.8.rst发布于 2020 年 2 月 3 日系统梳理该版本的核心变更Django 3.0 兼容支持、页面锁定机制从全员只读升级为锁定者独占编辑、新增锁定页面报告菜单以及 API 端点类重命名等破坏性升级项。读者将掌握 2.8 版本的新特性细节、从旧版本升级时需要注意的破坏性变更清单以及每项变更对应的源码实现位置便于在升级后快速定位与验证。一、版本总览2.8 带来了什么Wagtail 2.8 是面向 Django 3.0 时代的一次重要版本迭代核心看点集中在以下三方面Django 3.0 官方兼容该版本与 Django 3.0 完全兼容兼容性修复由 Matt Westcott 和 Mads Jensen 贡献。页面锁定Page Locking机制重构过去锁定页面后所有用户包括锁定者本人都只能只读访问2.8 改为锁定者获得独占编辑权其他用户无法编辑。同时新增 Reports 菜单管理员/版主可查看当前所有被锁定的页面并按需解锁。一批破坏性升级项包括移除 Django 2.0 支持、API 端点类重命名迁移、get_document_model导入路径调整、Page/Site模型移出 Django admin、嵌入媒体响应式包装类默认关闭等升级前务必逐项核对。该版本由 Karl Hobley 和 Jacob Topp-Mugglestone 主导页面锁定功能开发The Motley Fool 赞助了该特性。二、Django 3.0 支持与 Python 兼容性清理2.1 与 Django 3.0 的兼容2.8 是 Wagtail 全面拥抱 Django 3.0 的版本。Django 3.0 于 2019 年 12 月发布引入了对 Python 3.8 的支持、ASGI 异步支持等特性。Wagtail 2.8 通过兼容性修复确保在 Django 3.0 下稳定运行。2.2 Python 2.x 兼容代码清理该版本同时移除了残留的 Python 2.x 兼容代码由 Sergey Fedoseev 完成并合并了 flake8 配置。这意味着 Wagtail 2.8 及后续版本在代码层面已明确面向 Python 3 演进项目自身的运行环境也应确保使用 Python 3.6 及以上版本。三、改进的页面锁定Page Locking从全员只读到锁定者独占编辑3.1 旧行为与新行为对比页面锁定是 Wagtail 内容审核中的关键机制用于防止多人在同一页面上同时编辑造成冲突。2.8 之前一旦页面被锁定包括锁定者在内的所有用户都无法编辑页面整体变为只读。这种一刀切方式让锁定者自己也失去了编辑能力往往需要先解锁再编辑操作繁琐且容易产生中间状态。2.8 的核心变更在于锁定页面后锁定者本人仍然可以继续编辑拥有独占编辑权其他所有用户无法编辑只能只读访问锁定信息锁定人、锁定时间被完整记录管理员可查看并解除。3.2 从源码看锁定的实现当前仓库中页面锁定相关的数据模型与权限逻辑集中体现在 wagtail/models/pages.py页面模型持有locked、locked_by、locked_at字段见 wagtail/models/pages.py 附近的字段序列化清单其中locked_by记录执行锁定的用户locked_at记录锁定时间PagePermissionsTester提供权限判定方法user_has_lock()判断当前用户是否就是锁定者见 wagtail/models/pages.py、can_lock()是否允许执行锁定与can_unlock()是否允许解除锁定见 wagtail/models/pages.py。管理员侧的锁定/解锁操作视图位于 wagtail/admin/views/pages/lock.pyLockView.perform_operation会先检查permissions_for_user(user).can_lock()无权限则抛出PermissionDeniedUnlockView对应检查can_unlock()解锁成功后返回提示消息Page xxx is now unlocked.。3.3 新增 Reports 菜单锁定页面报告为了配合新锁定机制2.8 在管理后台的Reports报告菜单中新增了Locked pages锁定页面入口允许具有 unlock 权限的管理员/版主查看当前所有处于锁定状态的页面按锁定人Locked by、锁定时间Locked at和是否已发布live进行筛选直接在列表中执行解锁操作。对应实现为 wagtail/admin/views/reports/locked_pages.py 中的LockedPagesView使用WagtailFilterSet定义筛选器LockedPagesReportFilterSet其中locked_at使用DateRangePickerWidget日期范围选择器locked_by使用ModelChoiceFilter空选项文案为Anyoneget_queryset()将当前用户有 change 权限的页面与当前用户自己锁定的页面取并集再过滤lockedTrue从而保证报告展示内容与用户权限范围一致支持导出list_export扩展了locked_at、locked_by字段文件名格式为locked-pages-report-YYYY-MM-DD权限要求为unlockpermission_required unlock即只有具备解锁权限的用户才能查看该报告。报告模板位于 wagtail/admin/templates/wagtailadmin/reports/locked_pages_results.html解锁操作列表项模板为 wagtail/admin/templates/wagtailadmin/reports/listing/_list_unlock.html。3.4 配置项恢复旧行为若希望恢复 2.8 之前锁定后全员只读的行为可在项目设置中显式开启WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK True需要特别注意该设置只对 2.8 之后新锁定的页面生效。在 2.8 发布之前就已处于锁定状态的页面会继续保持旧的全员只读行为不受新机制影响。四、其他新增特性详解2.8 除两大主线特性外还有一批值得关注的增强以下结合当前仓库源码逐一说明。4.1 前端缓存Cloudflare API Token 支持与分批清理Wagtail 的前端缓存清理模块新增了对Cloudflare API Token的支持此前仅支持 API Key 方式用于在页面发布/更新时自动失效 CDN 缓存。相关实现位于 wagtail/contrib/frontend_cache/backends/cloudflare.pyCloudflareBackend通过requests.post调用 Cloudflare purge cache API由于 Cloudflare 单次 purge 请求存在数量上限2.8 起每 30 个 URL 分批发送。源码中定义了CHUNK_SIZE 30purge_batch()使用range(0, len(urls), self.CHUNK_SIZE)将批量 URL 切片后逐个分块调用_purge_urls测试用例 wagtail/contrib/frontend_cache/tests.py 中的test_cloudflare_purge_batch_chunked专门验证了 64 个 URL 会被正确分批清理防止单次请求超出 API 限制。4.2 嵌入媒体新增WAGTAILEMBEDS_RESPONSIVE_HTML设置此前 Wagtail 渲染嵌入媒体如 YouTube 视频时会自动在外层包装一个带responsive-object类名和padding-bottom内联样式的 div用于辅助响应式布局。2.8 起该包装默认不再添加改为通过设置显式控制WAGTAILEMBEDS_RESPONSIVE_HTML True在源码中该设置的判断位于 wagtail/embeds/models.pyEmbed.is_responsive属性首先检查settings.WAGTAILEMBEDS_RESPONSIVE_HTML是否为真再判断是否存在宽高比ratio。模板 wagtail/embeds/templates/wagtailembeds/embed_frontend.html 根据embed.is_responsive决定是否输出classresponsive-object与padding-bottom样式div{% if embed.is_responsive %} stylepadding-bottom: {{ embed.ratio_css }}; classresponsive-object{% endif %} {{ embed.html|safe }} /div对应测试见 wagtail/embeds/tests/test_rich_text.py开启设置时输出包含classresponsive-object关闭时则不包含。4.3 Admin APIpages 端点新增ancestors字段Admin API 的 pages 端点新增了ancestors字段便于前端获取页面的祖先层级链对面包屑导航、站点树渲染等场景很有帮助。4.4 文档管理缓存控制头与模型工具函数文档下载响应增加缓存控制头cache control headers提升文档静态资源的分发效率新增get_document_model_string函数并调整了get_document_model的位置使其在模型尚未加载时也能安全导入。当前实现位于 wagtail/documents/init.pyget_document_model_string()返回形如wagtaildocs.Document的字符串get_document_model()依赖它完成动态模型解析并提供了get_document_model_string()的便捷入口。4.5 其他改进文本字段 diff 行为优化比较页面修订版本时文本字段的差异展示更准确禁用输入控件对比度提升改善可访问性文档列表列名调整uploaded 更名为 created图片索引支持按标签筛选图片管理页可按 tag 过滤嵌套 InlinePanel 的部分实验性支持由 Matt Westcott、Sam Costigan、Andy Chosak、Scott Cranfill 共同贡献注意是部分 实验性支持生产环境使用需谨慎评估密码重置表单使用sensitive_post_parameters防止敏感参数被错误记录到日志StreamFieldPanel 与 ModelAdmin 自定义文档补全{{ block.super }}示例被补充到 ModelAdmin 自定义文档中所有包含extra_js/extra_css的模板wagtailsettings、modeladmin统一使用block.super避免覆盖父模板资源移除 Django admin 对Page与Site模型的管理见下文升级说明。五、Bug 修复清单2.8 修复了一批影响实际使用的问题按主题归类如下主题修复内容文档模块file_size与file_hash在文档文件变更后正确更新get_document_model移至模型未加载时也能导入的位置嵌入/富文本Jinja2 表单模板中 StructBlock 的 HTML 转义问题TableBlock 空白时不再导致update_index失败及前端渲染错误比较/审核比较引用了自定义主键模型的页面时不再报错模态框 chooser 搜索会取消上一次请求确保结果始终对应当前最新搜索关键词界面与布局FieldRowPanel带标题时布局问题修复搜索页 AJAX 调用后下拉框初始化问题修复项目模板URL 顺序修正确保 static / media URL 不被拦截国际化表单提交模型的verbose_name_plural补全解绑 l18n 库此前因安装错误被捆绑现已解决表单/权限所有含 wagtailsettings 与 modeladmin 的模板统一使用block.super输出extra_js/extra_css六、升级注意事项破坏性变更清单升级到 2.8 前请逐项核对以下变更它们可能影响现有代码与运行行为。6.1 移除 Django 2.0 支持Django 2.0 不再受支持。升级 Wagtail 之前请先将项目升级到 Django 2.1 或以上版本推荐直接使用 Django 3.0。6.2 编辑锁定行为变更如第三节所述锁定行为从全员只读变为锁定者独占编辑。此变更仅影响2.8 之后新锁定的页面升级前已锁定的页面维持旧行为。如需恢复旧行为设置WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK True6.3 嵌入响应式 HTML 默认关闭嵌入媒体不再默认包裹responsive-object。若你的前端样式依赖该包装类请在项目设置中加入WAGTAILEMBEDS_RESPONSIVE_HTML True6.4 API 端点类迁移*APIEndpoint→*APIViewSet为与 Django REST Framework 命名惯例保持一致PagesAPIEndpoint、ImagesAPIEndpoint、DocumentsAPIEndpoint分别更名为PagesAPIViewSet、ImagesAPIViewSet、DocumentsAPIViewSet并迁移到各自包内的views模块。当前仓库中的新位置为wagtail/api/v2/views.pyPagesAPIViewSetwagtail/images/api/v2/views.pyImagesAPIViewSetwagtail/documents/api/v2/views.pyDocumentsAPIViewSet升级时需更新 API 注册代码。旧代码from wagtail.api.v2.endpoints import PagesAPIEndpoint from wagtail.api.v2.router import WagtailAPIRouter from wagtail.images.api.v2.endpoints import ImagesAPIEndpoint from wagtail.documents.api.v2.endpoints import DocumentsAPIEndpoint api_router WagtailAPIRouter(wagtailapi) api_router.register_endpoint(pages, PagesAPIEndpoint) api_router.register_endpoint(images, ImagesAPIEndpoint) api_router.register_endpoint(documents, DocumentsAPIEndpoint)新代码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 api_router WagtailAPIRouter(wagtailapi) api_router.register_endpoint(pages, PagesAPIViewSet) api_router.register_endpoint(images, ImagesAPIViewSet) api_router.register_endpoint(documents, DocumentsAPIViewSet)6.5get_document_model导入路径变更get_document_model函数应改从wagtail.documents导入而不是wagtail.documents.modelsfrom wagtail.documents import get_document_model自定义文档模型的完整指引可参考文档 docs/reference/pages/models.md 中关于自定义模型的部分。这一调整的动机正是 Bug 修复中提到的使该函数在模型尚未加载时也能被安全导入参见 wagtail/documents/init.py。6.6Page与Site模型移出 Django adminPage与Site模型不再通过 Django admin 后台管理。如果你的项目确实需要在 Django admin 中维护这两个模型可在自己的应用中重新注册示例# my_app/admin.py from django.contrib import admin from wagtail.core.models import Page, Site admin.site.register(Site) admin.site.register(Page)注意注册Page模型会启用对整棵页面树的 Django admin 管理入口请结合你的权限体系谨慎评估是否必要。七、升级建议小结完成 Wagtail 2.8 升级时建议按以下顺序操作将 Django 升级到 2.1推荐 3.0Python 保持 3.x全局搜索项目中的APIEndpoint引用并替换为对应的APIViewSet同时修正 import 路径将get_document_model的导入改为from wagtail.documents import get_document_model检查是否依赖嵌入媒体的responsive-object包装按需开启WAGTAILEMBEDS_RESPONSIVE_HTML确认页面锁定新行为是否符合团队协作流程若需旧行为则设置WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK True如项目使用 Cloudflare 前端缓存可迁移到 API Token 认证方式并确认 30 条/批的分块清理逻辑检查 Django admin 中是否依赖Page/Site的管理入口按需重新注册运行项目测试套件重点回归页面锁定、嵌入渲染、文档上传/下载与 API 端点。升级后的验证可从 wagtail/admin/tests/pages/test_page_locking.py 与 wagtail/admin/tests/test_reports_views.py 中了解锁定与报告功能的官方测试行为作为自测的参考基线。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wagtail 2.8 版本发布全解析：Django 3.0 支持、独占式页面锁定与 API 端点迁移指南
Wagtail 2.8 版本发布全解析Django 3.0 支持、独占式页面锁定与 API 端点迁移指南【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail导读本文基于 Wagtail 官方 2.8 版本发布说明docs/releases/2.8.rst发布于 2020 年 2 月 3 日系统梳理该版本的核心变更Django 3.0 兼容支持、页面锁定机制从全员只读升级为锁定者独占编辑、新增锁定页面报告菜单以及 API 端点类重命名等破坏性升级项。读者将掌握 2.8 版本的新特性细节、从旧版本升级时需要注意的破坏性变更清单以及每项变更对应的源码实现位置便于在升级后快速定位与验证。一、版本总览2.8 带来了什么Wagtail 2.8 是面向 Django 3.0 时代的一次重要版本迭代核心看点集中在以下三方面Django 3.0 官方兼容该版本与 Django 3.0 完全兼容兼容性修复由 Matt Westcott 和 Mads Jensen 贡献。页面锁定Page Locking机制重构过去锁定页面后所有用户包括锁定者本人都只能只读访问2.8 改为锁定者获得独占编辑权其他用户无法编辑。同时新增 Reports 菜单管理员/版主可查看当前所有被锁定的页面并按需解锁。一批破坏性升级项包括移除 Django 2.0 支持、API 端点类重命名迁移、get_document_model导入路径调整、Page/Site模型移出 Django admin、嵌入媒体响应式包装类默认关闭等升级前务必逐项核对。该版本由 Karl Hobley 和 Jacob Topp-Mugglestone 主导页面锁定功能开发The Motley Fool 赞助了该特性。二、Django 3.0 支持与 Python 兼容性清理2.1 与 Django 3.0 的兼容2.8 是 Wagtail 全面拥抱 Django 3.0 的版本。Django 3.0 于 2019 年 12 月发布引入了对 Python 3.8 的支持、ASGI 异步支持等特性。Wagtail 2.8 通过兼容性修复确保在 Django 3.0 下稳定运行。2.2 Python 2.x 兼容代码清理该版本同时移除了残留的 Python 2.x 兼容代码由 Sergey Fedoseev 完成并合并了 flake8 配置。这意味着 Wagtail 2.8 及后续版本在代码层面已明确面向 Python 3 演进项目自身的运行环境也应确保使用 Python 3.6 及以上版本。三、改进的页面锁定Page Locking从全员只读到锁定者独占编辑3.1 旧行为与新行为对比页面锁定是 Wagtail 内容审核中的关键机制用于防止多人在同一页面上同时编辑造成冲突。2.8 之前一旦页面被锁定包括锁定者在内的所有用户都无法编辑页面整体变为只读。这种一刀切方式让锁定者自己也失去了编辑能力往往需要先解锁再编辑操作繁琐且容易产生中间状态。2.8 的核心变更在于锁定页面后锁定者本人仍然可以继续编辑拥有独占编辑权其他所有用户无法编辑只能只读访问锁定信息锁定人、锁定时间被完整记录管理员可查看并解除。3.2 从源码看锁定的实现当前仓库中页面锁定相关的数据模型与权限逻辑集中体现在 wagtail/models/pages.py页面模型持有locked、locked_by、locked_at字段见 wagtail/models/pages.py 附近的字段序列化清单其中locked_by记录执行锁定的用户locked_at记录锁定时间PagePermissionsTester提供权限判定方法user_has_lock()判断当前用户是否就是锁定者见 wagtail/models/pages.py、can_lock()是否允许执行锁定与can_unlock()是否允许解除锁定见 wagtail/models/pages.py。管理员侧的锁定/解锁操作视图位于 wagtail/admin/views/pages/lock.pyLockView.perform_operation会先检查permissions_for_user(user).can_lock()无权限则抛出PermissionDeniedUnlockView对应检查can_unlock()解锁成功后返回提示消息Page xxx is now unlocked.。3.3 新增 Reports 菜单锁定页面报告为了配合新锁定机制2.8 在管理后台的Reports报告菜单中新增了Locked pages锁定页面入口允许具有 unlock 权限的管理员/版主查看当前所有处于锁定状态的页面按锁定人Locked by、锁定时间Locked at和是否已发布live进行筛选直接在列表中执行解锁操作。对应实现为 wagtail/admin/views/reports/locked_pages.py 中的LockedPagesView使用WagtailFilterSet定义筛选器LockedPagesReportFilterSet其中locked_at使用DateRangePickerWidget日期范围选择器locked_by使用ModelChoiceFilter空选项文案为Anyoneget_queryset()将当前用户有 change 权限的页面与当前用户自己锁定的页面取并集再过滤lockedTrue从而保证报告展示内容与用户权限范围一致支持导出list_export扩展了locked_at、locked_by字段文件名格式为locked-pages-report-YYYY-MM-DD权限要求为unlockpermission_required unlock即只有具备解锁权限的用户才能查看该报告。报告模板位于 wagtail/admin/templates/wagtailadmin/reports/locked_pages_results.html解锁操作列表项模板为 wagtail/admin/templates/wagtailadmin/reports/listing/_list_unlock.html。3.4 配置项恢复旧行为若希望恢复 2.8 之前锁定后全员只读的行为可在项目设置中显式开启WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK True需要特别注意该设置只对 2.8 之后新锁定的页面生效。在 2.8 发布之前就已处于锁定状态的页面会继续保持旧的全员只读行为不受新机制影响。四、其他新增特性详解2.8 除两大主线特性外还有一批值得关注的增强以下结合当前仓库源码逐一说明。4.1 前端缓存Cloudflare API Token 支持与分批清理Wagtail 的前端缓存清理模块新增了对Cloudflare API Token的支持此前仅支持 API Key 方式用于在页面发布/更新时自动失效 CDN 缓存。相关实现位于 wagtail/contrib/frontend_cache/backends/cloudflare.pyCloudflareBackend通过requests.post调用 Cloudflare purge cache API由于 Cloudflare 单次 purge 请求存在数量上限2.8 起每 30 个 URL 分批发送。源码中定义了CHUNK_SIZE 30purge_batch()使用range(0, len(urls), self.CHUNK_SIZE)将批量 URL 切片后逐个分块调用_purge_urls测试用例 wagtail/contrib/frontend_cache/tests.py 中的test_cloudflare_purge_batch_chunked专门验证了 64 个 URL 会被正确分批清理防止单次请求超出 API 限制。4.2 嵌入媒体新增WAGTAILEMBEDS_RESPONSIVE_HTML设置此前 Wagtail 渲染嵌入媒体如 YouTube 视频时会自动在外层包装一个带responsive-object类名和padding-bottom内联样式的 div用于辅助响应式布局。2.8 起该包装默认不再添加改为通过设置显式控制WAGTAILEMBEDS_RESPONSIVE_HTML True在源码中该设置的判断位于 wagtail/embeds/models.pyEmbed.is_responsive属性首先检查settings.WAGTAILEMBEDS_RESPONSIVE_HTML是否为真再判断是否存在宽高比ratio。模板 wagtail/embeds/templates/wagtailembeds/embed_frontend.html 根据embed.is_responsive决定是否输出classresponsive-object与padding-bottom样式div{% if embed.is_responsive %} stylepadding-bottom: {{ embed.ratio_css }}; classresponsive-object{% endif %} {{ embed.html|safe }} /div对应测试见 wagtail/embeds/tests/test_rich_text.py开启设置时输出包含classresponsive-object关闭时则不包含。4.3 Admin APIpages 端点新增ancestors字段Admin API 的 pages 端点新增了ancestors字段便于前端获取页面的祖先层级链对面包屑导航、站点树渲染等场景很有帮助。4.4 文档管理缓存控制头与模型工具函数文档下载响应增加缓存控制头cache control headers提升文档静态资源的分发效率新增get_document_model_string函数并调整了get_document_model的位置使其在模型尚未加载时也能安全导入。当前实现位于 wagtail/documents/init.pyget_document_model_string()返回形如wagtaildocs.Document的字符串get_document_model()依赖它完成动态模型解析并提供了get_document_model_string()的便捷入口。4.5 其他改进文本字段 diff 行为优化比较页面修订版本时文本字段的差异展示更准确禁用输入控件对比度提升改善可访问性文档列表列名调整uploaded 更名为 created图片索引支持按标签筛选图片管理页可按 tag 过滤嵌套 InlinePanel 的部分实验性支持由 Matt Westcott、Sam Costigan、Andy Chosak、Scott Cranfill 共同贡献注意是部分 实验性支持生产环境使用需谨慎评估密码重置表单使用sensitive_post_parameters防止敏感参数被错误记录到日志StreamFieldPanel 与 ModelAdmin 自定义文档补全{{ block.super }}示例被补充到 ModelAdmin 自定义文档中所有包含extra_js/extra_css的模板wagtailsettings、modeladmin统一使用block.super避免覆盖父模板资源移除 Django admin 对Page与Site模型的管理见下文升级说明。五、Bug 修复清单2.8 修复了一批影响实际使用的问题按主题归类如下主题修复内容文档模块file_size与file_hash在文档文件变更后正确更新get_document_model移至模型未加载时也能导入的位置嵌入/富文本Jinja2 表单模板中 StructBlock 的 HTML 转义问题TableBlock 空白时不再导致update_index失败及前端渲染错误比较/审核比较引用了自定义主键模型的页面时不再报错模态框 chooser 搜索会取消上一次请求确保结果始终对应当前最新搜索关键词界面与布局FieldRowPanel带标题时布局问题修复搜索页 AJAX 调用后下拉框初始化问题修复项目模板URL 顺序修正确保 static / media URL 不被拦截国际化表单提交模型的verbose_name_plural补全解绑 l18n 库此前因安装错误被捆绑现已解决表单/权限所有含 wagtailsettings 与 modeladmin 的模板统一使用block.super输出extra_js/extra_css六、升级注意事项破坏性变更清单升级到 2.8 前请逐项核对以下变更它们可能影响现有代码与运行行为。6.1 移除 Django 2.0 支持Django 2.0 不再受支持。升级 Wagtail 之前请先将项目升级到 Django 2.1 或以上版本推荐直接使用 Django 3.0。6.2 编辑锁定行为变更如第三节所述锁定行为从全员只读变为锁定者独占编辑。此变更仅影响2.8 之后新锁定的页面升级前已锁定的页面维持旧行为。如需恢复旧行为设置WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK True6.3 嵌入响应式 HTML 默认关闭嵌入媒体不再默认包裹responsive-object。若你的前端样式依赖该包装类请在项目设置中加入WAGTAILEMBEDS_RESPONSIVE_HTML True6.4 API 端点类迁移*APIEndpoint→*APIViewSet为与 Django REST Framework 命名惯例保持一致PagesAPIEndpoint、ImagesAPIEndpoint、DocumentsAPIEndpoint分别更名为PagesAPIViewSet、ImagesAPIViewSet、DocumentsAPIViewSet并迁移到各自包内的views模块。当前仓库中的新位置为wagtail/api/v2/views.pyPagesAPIViewSetwagtail/images/api/v2/views.pyImagesAPIViewSetwagtail/documents/api/v2/views.pyDocumentsAPIViewSet升级时需更新 API 注册代码。旧代码from wagtail.api.v2.endpoints import PagesAPIEndpoint from wagtail.api.v2.router import WagtailAPIRouter from wagtail.images.api.v2.endpoints import ImagesAPIEndpoint from wagtail.documents.api.v2.endpoints import DocumentsAPIEndpoint api_router WagtailAPIRouter(wagtailapi) api_router.register_endpoint(pages, PagesAPIEndpoint) api_router.register_endpoint(images, ImagesAPIEndpoint) api_router.register_endpoint(documents, DocumentsAPIEndpoint)新代码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 api_router WagtailAPIRouter(wagtailapi) api_router.register_endpoint(pages, PagesAPIViewSet) api_router.register_endpoint(images, ImagesAPIViewSet) api_router.register_endpoint(documents, DocumentsAPIViewSet)6.5get_document_model导入路径变更get_document_model函数应改从wagtail.documents导入而不是wagtail.documents.modelsfrom wagtail.documents import get_document_model自定义文档模型的完整指引可参考文档 docs/reference/pages/models.md 中关于自定义模型的部分。这一调整的动机正是 Bug 修复中提到的使该函数在模型尚未加载时也能被安全导入参见 wagtail/documents/init.py。6.6Page与Site模型移出 Django adminPage与Site模型不再通过 Django admin 后台管理。如果你的项目确实需要在 Django admin 中维护这两个模型可在自己的应用中重新注册示例# my_app/admin.py from django.contrib import admin from wagtail.core.models import Page, Site admin.site.register(Site) admin.site.register(Page)注意注册Page模型会启用对整棵页面树的 Django admin 管理入口请结合你的权限体系谨慎评估是否必要。七、升级建议小结完成 Wagtail 2.8 升级时建议按以下顺序操作将 Django 升级到 2.1推荐 3.0Python 保持 3.x全局搜索项目中的APIEndpoint引用并替换为对应的APIViewSet同时修正 import 路径将get_document_model的导入改为from wagtail.documents import get_document_model检查是否依赖嵌入媒体的responsive-object包装按需开启WAGTAILEMBEDS_RESPONSIVE_HTML确认页面锁定新行为是否符合团队协作流程若需旧行为则设置WAGTAILADMIN_GLOBAL_PAGE_EDIT_LOCK True如项目使用 Cloudflare 前端缓存可迁移到 API Token 认证方式并确认 30 条/批的分块清理逻辑检查 Django admin 中是否依赖Page/Site的管理入口按需重新注册运行项目测试套件重点回归页面锁定、嵌入渲染、文档上传/下载与 API 端点。升级后的验证可从 wagtail/admin/tests/pages/test_page_locking.py 与 wagtail/admin/tests/test_reports_views.py 中了解锁定与报告功能的官方测试行为作为自测的参考基线。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考