自定义文章类型命名为media时WordPress Gutenberg编辑器失效求助

你碰到的问题核心是自定义文章类型（CPT）的名称media和WordPress原生媒体库的REST API端点重名了。WordPress默认已经有/wp/v2/media这个路由用来处理图片、视频等媒体文件，当你把CPT命名为media并开启show_in_rest时，会触发路由冲突——系统无法区分你请求的是内置媒体库还是自定义CPT，最终返回404错误，进而导致依赖REST API的Gutenberg编辑器加载失败，页面变成空白。

解决方法 #

有两个可行的方案供你选择：

方案1：自定义CPT的REST路由前缀 #

如果你坚持要保留media作为CPT的注册名称，可以通过rest_base参数修改它的REST路由前缀，避开和内置路由的冲突：

function cw_post_type() {
    register_post_type( 'media',
        array(
            'labels' => array(
                'name' => __( 'Media' ),
                'singular_name' => __( 'Media' )
            ),
            'has_archive' => true,
            'public' => true,
            'rewrite' => array('slug' => 'media'),
            'show_in_rest' => true,
            // 添加该参数自定义REST路由前缀
            'rest_base' => 'custom-media',
            'supports' => array('editor', 'title')
        )
    );
}
add_action( 'init', 'cw_post_type' );

修改后，你的自定义CPT的REST路由会变成/wp/v2/custom-media，既不会和内置路由冲突，Gutenberg编辑器也能正常加载。

方案2：修改CPT的内部注册名称 #

这是更简洁的方案，直接把CPT的内部标识改成不冲突的名称（比如custom_media），同时保留前台访问的slug为media：

function cw_post_type() {
    register_post_type( 'custom_media', // 修改内部注册名称
        array(
            'labels' => array(
                'name' => __( 'Media' ),
                'singular_name' => __( 'Media' )
            ),
            'has_archive' => true,
            'public' => true,
            'rewrite' => array('slug' => 'media'), // 前台访问链接依然是media
            'show_in_rest' => true,
            'supports' => array('editor', 'title')
        )
    );
}
add_action( 'init', 'cw_post_type' );

这个方案不需要调整REST路由，内部名称和内置媒体完全不冲突，前台访问体验也不受影响，同时能正常使用Gutenberg编辑器。

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