WordPress 主题打包与发布规范：版权、截图、readme 与检查清单

引言：代码没问题，包打得不对

一个常见场景：主题本身跑得很顺，客户也验收了，打包发出去之后对方反馈——「上传失败：缺少 style.css」「后台看不到预览图」「压缩包里怎么有 .git 和 node_modules」。这些都是打包环节的问题，与代码质量无关，但直接影响交付体验，也会影响官方目录的审核结果。

打包发布要处理四件事：版权与许可声明（GPL 与第三方资源授权）、必需的元信息文件（style.css 头部、readme.txt、screenshot.png）、包内容与结构（排除开发文件、目录层级正确）、代码合规（escaping、前缀、无混淆）。前三件是几分钟的机械劳动，但每一项都有具体的格式要求，写错了就得重来一轮。

原理分析：WordPress 怎么识别一个主题包

上传 zip 后，WordPress 解压到 wp-content/themes/，然后查找每个子目录下的 style.css 并解析头部注释。识别逻辑决定了两个硬约束：

1. zip 顶层必须是一个以主题 slug 命名的目录，里面才是主题文件。如果直接把文件打在 zip 根目录，或者套了两层目录，WordPress 会报「样式表缺失」。
2. style.css 头部的字段名必须准确：Theme Name、Theme URI、Author、Author URI、Description、Version、License、License URI、Text Domain、Tags、Requires at least、Tested up to、Requires PHP。少了 Theme Name 就无法识别；Text Domain 决定翻译文件能否被加载；Tags 必须是官方允许的标签列表里的值。

许可方面，WordPress 官方目录要求主题 100% GPL 兼容（通常是 GPLv2 or later）。这意味着：主题 PHP 代码必须 GPL；包含的图片、字体、JS 库也要兼容（注意部分字体与图标库是 SIL OFL 或 MIT，MIT 与 GPL 兼容但要在 readme 里注明；有使用限制的免费素材不可以用）。第三方资源要在 readme.txt 的 Copyright 段落里逐项列出名称、作者与许可。

保姆级实操

第一步：写完整的 style.css 头部

/*
Theme Name: 迷忙飞主题
Theme URI: https://mimangfei.com/themes/mimangfei
Author: 迷忙飞
Author URI: https://mimangfei.com
Description: 面向内容站点与外贸独立站的轻量 WordPress 主题，语义化模板、支持区块编辑器与 WooCommerce。
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Version: 1.2.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: mimangfei
Tags: blog, custom-logo, custom-menu, featured-images, translation-ready, block-patterns
*/

Tested up to 要填你实际测过的最新 WordPress 版本，别照抄核心版本号；Tags 只从官方标签列表里选，自造标签会被审核要求修改。

第二步：GPL 版权声明

每个 PHP 文件顶部建议加：

<?php
/**
 * 迷忙飞主题
 *
 * @package   mimangfei
 * @author    迷忙飞
 * @license   GPL-2.0-or-later
 * @link      https://mimangfei.com
 *
 * Copyright (C) 2026 迷忙飞
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 */

同时放一份 license.txt（GPLv2 全文）在主题根目录。

第三步：readme.txt 模板（官方目录格式）

=== 迷忙飞主题 ===

Contributors: mimangfei
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: blog, custom-logo, custom-menu, featured-images, translation-ready

== Description ==

面向内容站点与外贸独立站的轻量 WordPress 主题，语义化模板结构，支持区块编辑器与 WooCommerce。

== Installation ==

1. 后台进入「外观 → 主题 → 添加新主题 → 上传主题」，选择本压缩包。
2. 点击「启用」。
3. 进入「外观 → 自定义」设置 Logo、配色与页脚文字。

== Frequently Asked Questions ==

= 支持 WooCommerce 吗？ =

支持。主题已声明 WooCommerce 兼容，产品页与结算页样式已适配。

== Changelog ==

= 1.2.0 =
* 新增：区块模式三个（首屏、特性三栏、FAQ）
* 修复：移动端菜单焦点不可见的问题
* 优化：移除未使用的脚本加载

= 1.1.0 =
* 新增：主题选项面板（Customizer）
* 修复：分页在自定义查询下的 404

== Copyright ==

迷忙飞主题, Copyright 2026 迷忙飞
迷忙飞主题 is distributed under the terms of the GNU GPL.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

Photoshop 素材与字体说明：
* 截图中的示例图片来自 WordPress 官方示例数据，CC0
* 字体 PingFang SC / Microsoft YaHei，系统字体，非捆绑资源

Stable tag 必须与 style.css 的 Version 一致，否则官方目录里显示的版本号会错乱。

第四步：截图规范

• 文件名：screenshot.png（全小写）
• 尺寸：1200 × 900 像素（官方目录要求）
• 内容：必须是本主题的真实前台效果，不能用设计稿、竞品截图或带水印的图
• 格式：PNG，建议控制在 1MB 以内

# 快速确认尺寸
python -c "import struct;d=open('screenshot.png','rb').read(33);print(struct.unpack('>II',d[16:24]))"

第五步：排除开发文件

建 .distignore：

.git
.gitignore
.github
node_modules
vendor
src
sass
package.json
package-lock.json
composer.json
composer.lock
.distignore
*.log
.DS_Store
Thumbs.db

用 git 直接导出（自动遵守 .gitignore 与 .gitattributes 的 export-ignore）：

cd wp-content/themes/mimangfei
git archive --format=zip --output=../mimangfei-1.2.0.zip --prefix=mimangfei/ HEAD

或者手动打包：

cd wp-content/themes
zip -r mimangfei-1.2.0.zip mimangfei \
  -x "*/.git/*" "*/node_modules/*" "*/src/*" "*/.DS_Store" "*/dist/*"

第六步：验证包结构

unzip -l mimangfei-1.2.0.zip | head -20

正确结构应该是：

mimangfei/style.css
mimangfei/index.php
mimangfei/functions.php
mimangfei/screenshot.png
mimangfei/readme.txt
mimangfei/header.php
...

顶层只有 mimangfei/ 一个目录，且 style.css 就在它下面。若看到 mimangfei/mimangfei/style.css，说明套了两层，需要重新打包。

第七步：发布前最终检查

# 1) PHP 语法全量检查
find . -name "*.php" -print0 | xargs -0 -n1 php -l | grep -v "No syntax errors"

# 2) 编码规范
phpcs --standard=WordPress --extensions=php --ignore=vendor,node_modules .

# 3) 确认没有调试残留
grep -rn "var_dump\|print_r\|console.log\|TODO\|FIXME" --include="*.php" --include="*.js" .

再清一遍：临时文件、测试用的 test.php、写死的本地域名、以及任何形式的账号信息（发布包里绝不能出现服务器地址、数据库凭据、API Key）。

常见踩坑

1. zip 套了两层目录：上传报「找不到 style.css」，用 unzip -l 确认结构。
2. screenshot.png 尺寸不是 1200×900：官方目录直接要求重传，本地交付也会显示成拉伸的缩略图。
3. Stable tag 与 Version 不一致：目录页显示的版本与实际下载包不符，用户装到旧版本。
4. 把 node_modules 打进包：几万个小文件，服务器解压超时，且包含大量无关许可声明。
5. 第三方资源没写授权：审核时会逐个追问，字体与图标库最容易漏。
6. 案例：某主题打包时忘了排除 .git，压缩包 12MB，其中包含完整的提交历史，而历史里某个早期提交曾经把测试数据库的连接信息写进过配置文件——虽然当前代码里已删除，但 .git 里的历史对象仍能被还原。发布后被人爬到并公开。修复方式是重新打包并强制清理历史，教训是「发布包必须只包含运行所需文件」。
7. 版本号没递增：用户更新时检测不到新版本，或更新后浏览器仍用旧缓存，改版本号的习惯要养成。
8. readme 里写了「高级版请购买」：官方目录对 upsell 有严格限制，商业推广内容会被要求移除。

总结

发布前的清单可以压成六条：style.css 头部字段齐全且与 readme 一致；GPL 声明与 license.txt 就位；screenshot.png 为 1200×900 的真实截图；zip 顶层只有一个主题目录；开发文件与版本控制目录已排除；phpcs 与 php -l 无致命问题。走完这些，再跑一遍 Theme Check 自检 确认无 REQUIRED，就可以发布了。若主题适配了商城，别忘了同时核对 WooCommerce 兼容与模板覆盖 里提到的模板版本提示。