WordPress 主题文档：readme.txt 与 style.css 规范

发布于 作者:

对于任何一位 WordPress 主题开发者来说，文档往往是被放在后考虑的事情。但如果你希望自己的作品能被用户真正用起来，或者被其他开发者认可，文档就是绕不开的一环。它不仅是给用户看的说明书，更是你代码程度的体现。本文从官方文档出发，梳理了 WordPress 主题文档的核心要求，重点解读 readme.txt 的使用规范，以及 style.css 文件头信息的变化，希望能帮你理清头绪，少走弯路。

为什么主题文档如此重要

主题文档的价值，在于它清晰地划定了“这个主题能做什么”和“这个主题不做什么”的边界。

对用户来说，一份清晰的文档能让他们快速了解主题的特性、安装步骤，或是特殊的使用限制。比如，有些主题需要安装特定的插件才能运行，或者某些页面模板有特殊的设计要求，这些如果不写清楚，就会变成用户支持邮件里的“常见问题”。

对其他开发者来说，代码内的注释和说明决定了他们能否地基于你的主题进行二次开发。大多数人会选择通过子主题（Child Theme）的方式来修改功能，如果你的代码注释清晰、结构分明，他们就不需要从头读一遍几百行的 PHP 或 CSS 文件，节省的时间是实打实的。

核心要求：readme.txt 文件

根据 WordPress 官方主题目录的要求，自 2018 年 10 月 25 日起，所有新提交的主题都必须包含一个 readme.txt 文件。

注意：这个 readme.txt 不是随便写几句话就行，它有固定的格式要求，使用的是 WordPress 插件目录通用的 Markdown 标记格式。

readme.txt 通常放在主题的根目录下，它的主要作用是向 WordPress 主题目录（或者用户）展示主题信息。一个标准的 readme.txt 文件，结构大致如下：

txt

=== Theme Name ===
Contributors: username1, username2
Tags: tag1, tag2
Requires at least: 6.2
Tested up to: 6.4
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

这里写一句简短的主题描述，不要超过 150 个字符。

== Description ==

这里是主题的详细描述，可以写功能特性、设计理念，没有字符限制，可以使用 Markdown 语法来排版。

== Installation ==

告诉用户怎么安装这个主题，通常包括通过后台上传安装，或者通过 FTP 上传。

== Changelog ==

记录主题的版本更新历史，方便用户了解每次更新修复了什么、新增了什么。

== Frequently Asked Questions ==

这里放一些常见问题解答，比如如何设置首页、如何配置导航菜单等。

注：上面的代码块是为了演示结构，实际使用时需要按照规范填写内容。readme.txt 是主题文档的重要组成部分，格式是否标准，会直接影响主题在官方目录的审核和展示效果。

重要变更：Requires PHP 和 Requires at least

需要特别留意的是，自 WordPress 5.8 版本开始，主题的 readme.txt 文件不再被用于解析环境要求。也就是说，你在 readme.txt 里写的 Requires at least 和 Requires PHP 这两个字段，WordPress 核心程序会直接忽略。

那么，这两个关键的环境要求信息写在哪里？答案是 style.css 文件头。

这意味着，你在 style.css 的开头注释块中，必须显式地声明主题所需的低 WordPress 版本和 PHP 版本。例如：

css

/**
 * Theme Name: 你的主题名称
 * Theme URI: https://example.com
 * Author: 你的名字
 * Description: 主题描述
 * Version: 1.0.0
 * Requires at least: 6.2      <-- 这里声明低 WordPress 版本
 * Requires PHP: 7.4           <-- 这里声明低 PHP 版本
 * License: GPLv2 or later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: your-textdomain
 */

如果没有在 style.css 中正确声明这两个信息，当用户尝试在低版本 PHP 或 WordPress 环境下安装你的主题时，系统不会弹出友好的警告提示，这可能导致主题运行出错甚至网站崩溃。

关于 style.css 的补充说明

style.css 是 WordPress 主题的核心文件之一，它不仅仅是一份样式表。除了上面提到的 Requires at least 和 Requires PHP 之外，它开头的注释块还包含了主题的元数据，这些信息会在后台“外观 > 主题”页面中展示给用户，比如主题名称、描述、作者、版本号等。

如果你在开发子主题（Child Theme），还需要在 style.css 中通过 Template 字段来指定父主题的文件夹名称：

css

/**
 * Theme Name: 我的子主题
 * Template: twentytwentyfour     <-- 必须与父主题的文件夹名一致
 */

关于 style.css 的更多字段说明和规范，可以参考官方文档深入了解。

总结

  1. 文档是必需品：无论是面向用户的说明书，还是面向开发者的代码注释，都是主题开发不可分割的一部分。它能减少沟通成本，也能体现性。
  2. readme.txt 有固定格式：提交到 WordPress 官方目录的主题，必须包含符合 Markdown 格式的 readme.txt，内容至少要涵盖描述、安装、更新日志等基本模块。
  3. 环境要求写对地方：从 WordPress 5.8 开始，Requires at least 和 Requires PHP 这两个要求必须写在 style.css 的文件头中，写在 readme.txt 里是无效的。
  4. style.css 是主题名片：style.css 的文件头注释不仅控制着主题在后台的显示信息，也承担了向 WordPress 核心程序宣告环境兼容性的重要职责。