WordPress
插件开发
指南
团队的 source → build → release 流程。足以支持本地开发、打包 ZIP、安装到 WordPress 生产环境。.
PHP 8.x
WordPress hooks API
@wordpress/scripts
React (管理后台 UI)
Webpack 5
npm 脚本
Node.js ≥ 18
ZIP 发布包
目录结构
源码 (开发)
my-plugin.php ← 主插件文件
includes/ ← PHP 运行时
class-core.php
class-admin.php
admin/
src/ ← 在此处编写代码
index.js ← 入口点
components/
dist/ ← 构建输出
index.js
index.asset.php
index.css
languages/ ← i18n
node_modules/ ← .gitignore
releases/ ← .gitignore
配置文件
package.json
webpack.config.js ← 如有自定义需求
.gitignore
BUILD.md
readme.txt
uninstall.php
// ✓ 正确 — 从 dist 加载
plugins_url(‘admin/dist/index.js’)
// ✗ 错误 — 不要从 src 加载
plugins_url(‘admin/src/index.js’)
工作流
Local Development
本地开发
Chạy watch mode, sửa JS/React → build tự động, F5 WP là thấy ngay.
01
Cài dependencies
只需首次。要求 Node.js ≥ 18。.
npm install
02
Bật watch mode
Webpack 监听：在 中保存文件
admin/src/ → tự build ra admin/dist/. 在 WP 中需要手动按 F5。.npm run start
03
在本地 WP 上测试
创建符号链接到
wp-content/plugins/ 或使用 Local by Flywheel。.Build & Release
打包 ZIP，安装 WP
构建生产版，打包干净的 ZIP —— 服务器上无需 npm。.
01
Build production
Webpack 构建，包含压缩 + tree-shaking。.
npm run build
02
打包 ZIP
脚本复制正确文件，排除
node_modules 和 admin/src.npm run package
# → releases/plugin-v1.0.0.zip
# → releases/plugin-v1.0.0.zip
03
校验 SHA256
sha256sum releases/plugin-v1.0.0.zip
✓
上传到 WordPress
Admin → Plugins → Add New → Upload。激活。服务器上无需 npm。.
npm 脚本 — 备忘单
npm run start
监听模式 — 日常开发
webpack –watch –mode development
npm run build
生产构建 — 发布前
webpack –mode production + minify
npm run package
打包干净的 ZIP 到 releases/
排除 src/ node_modules/ .git/
npm run lint:js
遵循 WP 标准的 JS 代码检查
wp-scripts lint-js
npm run format
自动格式化代码
wp-scripts format (prettier)
npm run release
Lint → 构建 → 打包
在一条命令中执行检查 + 构建 + 打包
ZIP 发布包 — 内部与外部
✓ ZIP 包中包含
my-plugin.php主插件文件
includes/完整的 PHP 运行时文件
admin/dist/已构建好的 JS/CSS
languages/i18n 语言包（如有）
readme.txtWP.org 格式
uninstall.php删除插件时的清理脚本
✗ ZIP 包中不包含
node_modules/依赖仅用于开发
admin/src/源码，不运行
.git/仓库元数据
package.json / webpack.config.js构建配置
.test.js / debug-.php内部测试文件
.env / .DS_Store本地机器文件
重要规则
正确做法
入队自
admin/dist/读取
index.asset.php 获取依赖 + 版本使用
wp_localize_script() 传递数据 PHP → JS开展
npm run build 之前 npm run package按条件加载 —— 仅在需要的页面 enqueue
全部添加前缀：
dps_, DPS_不要做
入队自
admin/src/在 PHP 中硬编码版本哈希
为了
node_modules/ 在 ZIP 中在生产服务器上执行 npm install
在此处执行重量级 DB 查询
init hookecho $_POST['x'] 未进行 sanitize/escape生产就绪清单
Build & Release
✓
npm run build 无错误 → admin/dist/✓
ZIP 可安装，激活无错误 —— 无需 npm 服务器
✓
ZIP 不包含
node_modules/ 还是 src/✓
反馈：文件列表 + ZIP 路径 + SHA256
安全
✓
所有 PHP 文件都有
if (!defined('ABSPATH')) exit;✓
所有 AJAX/form：nonce 校验 +
current_user_can()✓
输入已清理，输出已转义
效果
✓
资源按条件加载 —— 不在全站加载
✓
脚本：
in_footer: true + strategy: defer✓
不要在此处执行重量级 DB 查询
init hook规范
✓
所有 function/class/option 都有前缀
dps_✓
插件头：
最低要求, PHP 版本要求✓
所有字符串使用 i18n，,
uninstall.php 清理干净✓
BUILD.md 完整：install, build, package, test
