WordPress 主题（Theme）开发超详细教程-新知幻

下面给出一份“从 0 到 1”的 WordPress 主题（Theme）开发超详细教程。
分 7 个阶段、30+ 个步骤，覆盖环境、文件结构、模板层级、循环（Loop）、钩子、菜单、小工具、自定义区块（Block）、国际化、打包上线等全部关键知识点。只要跟着敲一遍，你就能独立做出可发布的主题。

阶段 1：准备工作

1.1 运行环境

本地：推荐 Local WP、XAMPP、Laragon 一键包
线上：任意支持 PHP 7.4+ / MySQL 5.7+ 的主机即可
调试：在 wp-config.php 中加三行

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );

目录规划

wp-content/themes/
└── mytheme/                ← 你的主题文件夹
├── style.css           ← 必须，主题元数据
├── index.php           ← 必须，默认模板
├── functions.php       ← 必须，功能总入口
├── screenshot.png      ← 推荐，800×600 封面图
├── css/
├── js/
├── template-parts/     ← 复用结构
├── assets/ (images/fonts/svg)
└── languages/          ← .pot/.po/.mo 语言包

最小可运行主题（Hello Theme）

2.1 style.css 头部注释

/*
Theme Name: MyTheme
Description: 从零开发教学主题
Author: Your Name
Version: 1.0.0
Requires at least: 5.9
Tested up to: 6.6
Requires PHP: 7.4
Text Domain: mytheme
*/

index.php（最简版）

<?php get_header(); ?>
<main>
  <?php
    if ( have_posts() ) :
      while ( have_posts() ) : the_post();
        the_title( '<h2><a href="' . esc_url( get_permalink() ) . '">', '</a></h2>' );
        the_content();
      endwhile;
    else :
      echo '<p>暂无文章</p>';
    endif;
  ?>
</main>
<?php get_footer(); ?>

header.php

<!doctype html>
<html <?php language_attributes(); ?>>
<head>
  <meta charset="<?php bloginfo( 'charset' ); ?>">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<header>
  <h1><a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a></h1>
  <p><?php bloginfo( 'description' ); ?></p>
</header>

footer.php

<footer>
  <p>&copy; <?php echo date( 'Y' ); ?> <?php bloginfo( 'name' ); ?></p>
  <?php wp_footer(); ?>
</body>
</html>

functions.php（最简版）

<?php
// 主题资源加载
add_action( 'wp_enqueue_scripts', function () {
  wp_enqueue_style( 'mytheme-style', get_stylesheet_uri() );
} );

// 翻译文件
load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );

此时后台已能看到并启用主题，网站可正常访问。

模板层级与常用模板
WordPress 根据查询类型自动匹配模板，优先级由高到低

查询类型	最优先模板	无则回退
首页	front-page.php	index.php
文章	single-{post-type}.php	single.php → singular.php → index.php
页面	page-{slug}.php	page-{id}.php → page.php → singular.php → index.php
分类	category-{slug}.php	category-{id}.php → category.php → archive.php → index.php
标签	tag-{slug}.php	tag.php → archive.php → index.php
404	404.php	index.php

练习：

复制 index.php → single.php，删除 the_content() 外的所有 HTML，仅保留正文，观察文章页变化。
复制 single.php → page.php，把 the_content() 包一层 <div class="page-content">

阶段 4：functions.php 常用功能

4.1 主题支持（一次性声明）

add_action( 'after_setup_theme', function () {
  add_theme_support( 'post-thumbnails' );      // 特色图
  add_theme_support( 'title-tag' );            // 自动生成 <title>
  add_theme_support( 'html5', [ 'comment-list', 'search-form', 'gallery' ] );
  add_theme_support( 'wp-block-styles' );      // Gutenberg 样式
  add_theme_support( 'align-wide' );           // 放宽对齐
  register_nav_menus( [
    'primary' => __( '主导航', 'mytheme' ),
    'footer'  => __( '底部菜单', 'mytheme' ),
  ] );
} );

4.2 资源打包（含版本号 & 条件加载）

add_action( 'wp_enqueue_scripts', function () {
  $ver = wp_get_theme()->get( 'Version' );
  wp_enqueue_style( 'bootstrap', 'https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css', [], '5.3.3' );
  wp_enqueue_style( 'mytheme-style', get_stylesheet_uri(), [ 'bootstrap' ], $ver );
  wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/js/main.js', [ 'jquery' ], $ver, true );
} );

4.3 侧边栏/小工具区域

add_action( 'widgets_init', function () {
  register_sidebar( [
    'name'          => __( 'Blog Sidebar', 'mytheme' ),
    'id'            => 'sidebar-1',
    'before_widget' => '<section class="widget %2$s">',
    'after_widget'  => '</section>',
    'before_title'  => '<h3 class="widget-title">',
    'after_title'   => '</h3>',
  ] );
} );

前端调用：

if ( is_active_sidebar( 'sidebar-1' ) ) {
  dynamic_sidebar( 'sidebar-1' );
}

阶段 5：模板拆分与复用

5.1 使用 get_template_part

在 index.php / archive.php 内：

while ( have_posts() ) :
  the_post();
  get_template_part( 'template-parts/content', get_post_type() );
endwhile;

创建文件：

template-parts/content.php ← 通用
template-parts/content-post.php ← 仅 post
template-parts/content-product.php ← 自定义类型

5.2 分页导航

the_posts_pagination( [
  'mid_size' => 2,
  'prev_text' => __( '上一页', 'mytheme' ),
  'next_text' => __( '下一页', 'mytheme' ),
] );

阶段 6：样式 / JS / 构建流程

6.1 Sass/SCSS → CSS

src/scss/
├── _variables.scss
├── _header.scss
└── main.scss

使用 npm i -D sass 监听：

"scripts": {
  "dev": "sass --watch src/scss:assets/css --style=expanded"
}

6.2 自动刷新

Browsersync + webpack 或 Vite
Local WP 内置 live reload

6.3 图片/字体

小图标 → SVG sprite
大图 → 压缩后放 assets/images
字体 → assets/fonts，使用 @font-face 引入

阶段 7：国际化、打包与发布

7.1 生成 .pot

wp i18n make-pot . languages/mytheme.pot

在 functions.php 加载：

load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );

所有文字用 __( 'xxx', 'mytheme' ) 包装。

7.2 压缩包规范

删除 node_modules、src、*.log、.git
仅保留：php、css、js、png、mo、po、txt、LICENSE
压缩成 mytheme.zip

7.3 上架官方目录

访问 https://themes.trac.wordpress.org/
上传 zip → SVN → 审核 → 发布
后续通过 SVN 更新版本

进阶路线图（可选）

区块主题（Block Theme）：学习 theme.json、区块模板、模板部件
全站编辑（FSE）：使用 site-editor 替代传统小工具/自定义izer
Headless：WP 做后台，Next.js/Nuxt 渲染前端
WooCommerce 主题：覆盖 woocommerce/ 模板文件、商品循环、结账流程

文章版权归作者所有，未经允许请勿转载。

THE END

源码资源

WordPress 主题（Theme）开发超详细教程