使用Timber/Twig开发WordPress主题时，主题定制API无法显示问题求助

我之前在开发Timber主题时也碰到过类似的定制器选项不显示的问题，给你几个实用的排查思路：

1. 确认定制器代码的加载时机与钩子挂载 #

Timber主题的functions.php加载逻辑和普通WP主题略有差异，先检查你的定制器注册代码是不是挂在了正确的钩子上：

• 确保你是用add_action('customize_register', '你的定制器函数名')来挂载的，没有拼写错误
• 可以把定制器注册代码放在after_setup_theme钩子的回调函数里，和Timber初始化一起执行，比如：

function mytheme_theme_setup() {
    // 先注册定制器钩子
    add_action('customize_register', 'mytheme_customize_header');
    // 再初始化Timber
    Timber::init();
}
add_action('after_setup_theme', 'mytheme_theme_setup');

2. 验证定制器函数是否被调用 #

在你的定制器注册函数里加一行调试代码，比如：

function mytheme_customize_header($wp_customize) {
    // 加这行看函数是否执行
    error_log('定制器函数已触发');
    // 你的注册设置和控件代码...
}

然后打开WP后台的定制器页面，去服务器的错误日志里看有没有这条记录。如果没有，说明函数根本没被调用，大概率是钩子挂载出错了。

3. 检查定制器代码的正确性 #

确认你的设置和控件注册代码没有语法错误：

• 比如注册图片控件时，有没有正确实例化WP_Customize_Image_Control，参数有没有传对（尤其是$wp_customize对象、设置ID和section名称）
• 如果是用自定义section，要先确保你已经创建了这个section：

$wp_customize->add_section('mytheme_header_section', array(
    'title' => __('页眉设置', 'mytheme'),
    'priority' => 30,
));

4. 排查冲突问题 #

• 暂时禁用所有第三方插件，看定制器选项会不会出现，排除插件冲突
• 把你的定制器代码复制到官方的Timber Starter Theme里测试，如果能正常显示，说明是你当前主题的其他代码影响了定制器加载

给你一个可参考的完整示例 #

function mytheme_customize_header($wp_customize) {
    // 添加自定义section
    $wp_customize->add_section('mytheme_header_section', array(
        'title' => __('页眉设置', 'mytheme'),
        'priority' => 30,
    ));

    // 注册页眉图片设置
    $wp_customize->add_setting('custom_header_image', array(
        'default' => get_template_directory_uri() . '/images/default-header.jpg',
        'sanitize_callback' => 'esc_url_raw',
    ));

    // 添加图片选择控件
    $wp_customize->add_control(new WP_Customize_Image_Control(
        $wp_customize,
        'custom_header_image',
        array(
            'label' => __('选择页眉图片', 'mytheme'),
            'section' => 'mytheme_header_section',
            'settings' => 'custom_header_image',
        )
    ));
}
add_action('customize_register', 'mytheme_customize_header');

如果按上面的步骤排查后还是有问题，可以检查一下Timber的版本，确保是最新稳定版，旧版本可能存在一些兼容性问题。

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