自定义主题致WordPress媒体库失效，修复报错后仍异常求因

嘿，我碰到过不少自定义主题导致WordPress媒体库罢工的情况，虽然你已经修复了PHP和JS的报错，但还有几个容易被忽略的点值得逐一排查：

• 主题对媒体库查询的钩子冲突
  自定义主题常通过pre_get_posts或wp_query钩子修改内容查询，但如果不小心把**附件类型（attachment）**给过滤掉了，媒体库就会显示为空。你可以去主题的functions.php里找找类似add_filter('pre_get_posts', 'xxx')的代码，检查逻辑里有没有限制post_type为非attachment的情况，临时注释掉这类代码测试下是否恢复。

• REST API被主题拦截或禁用
  WordPress 4.9+的媒体库核心功能依赖REST API，主题可能通过过滤器禁用了REST API，或者给请求加了错误的权限校验。你可以直接访问站点的wp-json/wp/v2/media路径，如果返回403错误或空数据，大概率是这个问题。检查主题里有没有rest_authentication_errors或rest_enabled相关的过滤代码，比如add_filter('rest_enabled', '__return_false')这类禁用逻辑。

• 媒体上传路径的配置或权限问题
  主题可能通过upload_dir过滤器自定义了上传路径，但路径不存在、权限不正确（目录一般设为755，文件644），或者硬编码的路径和WordPress默认配置冲突。你可以去后台「设置-媒体」里确认上传路径是否正确，也通过FTP检查wp-content/uploads目录的权限和文件存在情况。

• 主题JS与新版媒体库的静默兼容性问题
  虽然你修复了明显的JS报错，但WordPress 4.9.6可能对媒体库的JS组件（比如Backbone视图）做了细微调整，主题里的自定义JS可能逻辑上和新版不兼容，却没抛出错误。打开浏览器开发者工具（F12）的控制台，看看有没有静默的逻辑错误，或者临时切换到默认主题（比如Twenty Seventeen）测试——如果切换后媒体库正常，那就是主题JS和新版媒体库的适配问题。

• 缓存残留导致旧代码未更新
  有时候代码修复了，但浏览器缓存、CDN缓存或者服务器端的OPcache/Redis缓存还存着旧的主题文件。试试清除浏览器缓存，或者给主题的JS/CSS文件加个版本号（比如script.js?v=20240501）强制刷新；服务器端的话，联系主机商清除缓存或者重启缓存服务。

• 自定义媒体库模板的兼容性问题
  如果主题自定义了媒体库的后台模板（比如修改了wp-admin下的媒体相关文件，或者通过钩子替换了媒体库的视图），这些模板可能和WordPress 4.9.6的新版模板结构不匹配。检查主题里有没有admin目录下的媒体模板文件，或者media_upload_tabs这类修改媒体库界面的钩子，临时移除相关代码测试。

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