WordPress 主题从零：style.css 头部那段注释不是摆设

第一次做 WordPress 主题，很多人是从网上拷一个 index.php 开始改的。改完传上去，后台主题列表里能看到，点启用，站就变样了。整个过程里 style.css 顶部那段注释几乎没人看过。

但那段注释是 WordPress 识别一个主题的唯一凭据。没有它，目录就算放进 wp-content/themes/，后台也不会列出来。

最小能识别的版本

/*
Theme Name: 我的主题
Author: 张三
Version: 1.0.0
*/

这样其实就够了。四行。后台会显示名称、作者、版本。

但只写这几行，后台的主题卡片会空掉一大块，描述没有、截图没有、标签没有，看着像半成品。

完整的那一套

/*
Theme Name: 我的主题
Theme URI: https://example.com/my-theme
Author: 张三
Author URI: https://example.com
Description: 一个拿来练手的双栏博客主题
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
Tags: blog, two-columns, custom-menu, featured-images
*/

Requires at least 和 Tested up to 这两行以前没人管，现在后台会拿它们做兼容性提示。写低了不报错，但用户装上去看到「未在本版本测试过」的黄色提示，第一印象就差了。

Requires PHP 更实在。主题里用了箭头函数、用了 ??，就得写 7.4 或 8.0。写在头部，WordPress 会在低版本 PHP 上直接拦住不启用，比白屏强得多。

Text Domain 这件事，写错了后面全歪

翻译函数长这样：

__('阅读更多', 'my-theme')

第二个参数必须跟头部 Text Domain 完全一致。我见过写 mytheme 的，也见过写 my_theme 的，而头部写的是 my-theme。三个地方不一致，翻译文件加载了也不生效。

而且这个值一旦发布就不能改了。改了整个语言包全部失效，用户升级完发现站上冒出一堆英文。

Tags 不是随便写的

我一开始以为 Tags 是自由标签，写了一堆「简洁」「响应式」「SEO 友好」。结果后台不显示。

WordPress 有一份固定的主题标签词表，只能用里面列出的词，比如 blog、two-columns、custom-logo、featured-images、full-width-template。写了词表外的值，会被静默丢弃，不报错。

这一点挺坑。不报错的东西最容易让人以为是缓存问题，我为此清了两遍缓存。

screenshot.png 的尺寸

主题目录里放一张 screenshot.png，后台主题卡片就会显示它。

推荐 1200×900。我试过 1920×1080，能显示，但会被裁掉两边，卡片里看着怪。也试过 600×450，糊得厉害。

格式上 png 和 jpg 都认。jpg 体积小，但如果截图里有文字，边缘容易出噪点。

目录里最少要有哪几个文件

严格说，只有 style.css 和 index.php 两个文件就能算一个主题。WordPress 会用它兜住所有页面。

但真这么做，所有页面长得一模一样，分类页、搜索页、单篇全是首页列表。用户装上去第一件事就是来问你为什么点进去没变化。

所以我一般起步就建这几个：

• index.php —— 兜底模板
• header.php / footer.php —— 公共头尾
• sidebar.php —— 侧栏
• single.php —— 单篇文章
• page.php —— 独立页面
• archive.php —— 归档
• search.php —— 搜索结果
• 404.php —— 找不到

八个文件，先建空的也行，里面写个注释标一下这是哪个模板。后面慢慢填。

先有空文件的好处是，你在页面上点来点去，看浏览器开发者工具或者用模板调试插件，能立刻知道当前走的是哪个文件。全塞在 index.php 里，出事只能靠猜。

我第一个主题就是全塞在 index.php，四百多行，改到第三天自己都不认识那段 if 是干什么的了。