WordPress主题必须包含style.css（含标准注释头）和index.php才能被识别；functions.php中禁止直接echo输出，应挂载到钩子；模板按层级规则匹配，调试需开启WP_DEBUG并检查$wp_query状态。
主题必须有 style.css 和 index.php 才能被 WordPress 识别
WordPress 不是靠文件夹名或配置文件注册主题，而是扫描 wp-content/themes/ 下每个子目录，检查是否存在合法的 style.css 文件头。缺这个文件，后台“外观→主题”里根本不会显示你的主题。
常见错误现象：style.css 放错了位置（比如放在子文件夹里）、文件编码不是 UTF-8 无 BOM、注释格式少了一行或用了中文冒号。WordPress 只认标准注释块，且必须以 /* 开头、*/ 结尾，中间每行以 * 起始。
-
Theme Name:必须有，且不能为空或纯空格 -
Text Domain:建议填小写英文，后续做多语言要用到 -
Template:如果是子主题，必须写父主题文件夹名（不是主题显示名） - 别用
@package或自定义字段代替必需字段，WordPress 不解析它们
functions.php 是主题逻辑入口，但不能直接 echo 输出
很多新手在 functions.php 里写 echo "hello";，结果导致“Headers already sent”错误，或者页面顶部出现意外文字。这是因为 functions.php 在 WordPress 加载早期就被引入，此时 HTML 尚未开始输出，直接 echo 会破坏 HTTP 头发送流程。
正确做法是把输出逻辑挂到 WordPress 的动作钩子上，比如 wp_head、wp_footer 或 the_content。这些钩子确保代码在合适时机执行。
立即学习“PHP免费学习笔记（深入）”；
- 想加 JS/CSS？用
wp_enqueue_script()和wp_enqueue_style()，别直接echo <script> - 想改文章内容？用
add_filter('the_content', 'my_content_filter');，函数内 return 修改后的字符串 - 想初始化设置？用
after_setup_theme钩子，比直接写在functions.php顶层更安全 - 避免在
functions.php里写require_once绝对路径，用get_template_directory()或get_stylesheet_directory()
模板文件名和调用顺序决定页面渲染逻辑
WordPress 不是按文件名顺序加载模板，而是有一套明确的 模板层级规则。比如访问某篇文章，它会依次查找：single-{post_type}-{slug}.php → single-{post_type}.php → single.php → index.php。找不到就回退，直到命中 index.php —— 这就是为什么所有主题都必须有 index.php。
容易踩的坑是误以为改了 page.php 就能控制所有页面，其实如果页面启用了某个页面模板（如 front-page.php），它会优先匹配那个，而不是 page.php。
-
front-page.php专用于首页（无论是否设为静态页） -
home.php仅用于博客文章列表页（即“最新文章”那页） -
archive.php匹配分类、标签、作者、日期归档页，但不包括搜索页（那是search.php） - 自定义文章类型需要对应
archive-{post_type}.php和single-{post_type}.php，否则回落到通用模板
调试时别只看浏览器源码，要查 PHP 错误和 WP_Query 状态
页面空白、内容错乱、循环输出重复数据……这些问题光看前端 HTML 很难定位。真正关键的是 PHP 层有没有报错，以及当前查询对象 $wp_query 是否符合预期。
开发阶段务必打开 WP_DEBUG，并在 wp-config.php 中加上：
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
这样错误会记录到 wp-content/debug.log，而不是炸在页面上。再配合 var_dump($wp_query->query_vars) 或 error_log(print_r($wp_query->posts, true))，能快速确认当前是不是你认为的那个页面类型。
- 用
is_single()判断时，注意它返回 true 的前提是主查询（main query）是单篇文章，不是你自己 new WP_Query() 的实例 - 模板里别直接用
query_posts()，它会覆盖主查询，引发分页失效、SEO 标签错乱等问题 - 子主题继承父主题模板时，如果父主题用了
get_template_part()，子主题同名文件会被自动优先加载，但路径不能带扩展名 - 启用 OPcache 或对象缓存插件后，修改 PHP 文件可能不生效，记得清缓存再测试
主题开发最麻烦的地方不在写代码，而在理解 WordPress 如何根据 URL 和查询参数决定走哪个模板、触发哪些钩子、加载哪些数据。很多问题不是语法错，是没意识到当前上下文已经不是你以为的那个上下文。
