Vite 8 + Tailwind 4 + Blade：WordPress 主题现代化的完整方案
如果你正在做 WordPress 主题开发，可能已经受够了传统的 PHP 模板 + jQuery + 手工编译 CSS。这篇教程会带你用现代化的工具链重新搭一个主题，全程不超过 30 分钟。
为什么是 Vite 8
Vite 是当前前端的事实标准构建工具。Vite 8 在 WordPress 生态里特别好用，原因有几个：
- 冷启动几乎零延迟 — ESM 原生支持，不像 Webpack 要先打包整个依赖图
- HMR 热更新 — 改一行 CSS，浏览器立刻看见，不用刷新页面
- Tailwind 4 深度集成 — 官方
@tailwindcss/vite插件零配置 - Sage 11 默认支持 — Roots 团队的 Sage starter theme 已经把 Vite 集成好
项目初始化
假设你已经有了一个 WordPress 站点（PHP 8.1+，MySQL 5.7+）。我们直接用 Sage 11：
cd /www/wwwroot/your-site/wp-content/themes/
composer create-project roots/sage your-theme-name
cd your-theme-name
npm install
安装完后你会看到这样的目录结构：
your-theme-name/
├── app/ # PHP 业务代码
│ ├── Providers/ # 服务提供者
│ ├── View/Composers/ # 视图数据注入
│ └── setup.php
├── resources/
│ ├── views/ # Blade 模板
│ ├── css/app.css
│ └── js/app.js
├── public/build/ # 编译产物（git 忽略）
├── vite.config.js
├── package.json
└── composer.json
配置 vite.config.js
Sage 11 默认的 vite.config.js 已经够用，但如果你要加自定义路径别名，可以这样：
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite';
import laravel from 'laravel-vite-plugin'
export default defineConfig({
base: '/app/themes/your-theme-name/public/build/',
plugins: [
tailwindcss(),
laravel({
input: [
'resources/css/app.css',
'resources/js/app.js',
],
refresh: true,
}),
],
})
配置 Tailwind 4
Tailwind 4 抛弃了 tailwind.config.js，改成 CSS 驱动的配置。在 resources/css/app.css 里：
@import "tailwindcss" theme(static);
@source "../../app/*/.php";
@source "../*/.blade.php";
@source 指令告诉 Tailwind 去扫描哪些文件，找出实际用到的 class。没有用到的 class 在 build 时会被 tree-shake 掉。
Blade 模板基础
Sage 默认用 Laravel 的 Blade 引擎。WordPress 用 Blade 的好处是：
- 组件化 — 复用 header / footer / card 不再复制粘贴
- 指令丰富 —
@if @foreach @include @yield比原生 PHP优雅 - Laravel 生态 — 可以用 Eloquent、Collection、Carbon（Acorn 自带）
一个简单的文章模板：
<article class="max-w-2xl mx-auto py-8">
<h1 class="text-3xl font-bold">{{ $title }}</h1>
<div class="text-gray-500 mt-2">{{ get_the_date() }}</div>
<div class="prose mt-6">
@php(the_content())
</div>
</article>
开发与构建
# 开发（带 HMR）
npm run dev
生产构建
npm run build
重点：Vite 8 build 完成后，必须把 public/build/manifest.json 复制到 public/manifest.json，否则 Acorn 5 找不到 manifest，会导致页面引用旧的 CSS/JS hash，404 全裸：
cp public/build/manifest.json public/manifest.json
我把这个步骤写到了 build.sh，一行命令搞定：
#!/usr/bin/env bash
npx vite build
cp public/build/manifest.json public/manifest.json
chown -R www:www public/
Acorn 5 vendor patch 必做
Sage 11 用 Acorn 5.0.0-beta.2，但有两个地方对 Vite 8 不兼容。直接 vendor patch：
Patch 1: vendor/roots/acorn/src/Roots/Acorn/Assets/Manifest.php 第 47 行附近：
// 原版
$value = $manifest[$key] ?? null;
// 改成（Vite 8 manifest 格式是 object）
$value = $manifest[$key] ?? null;
if (is_array($value)) {
$value = (object) $value;
}
Patch 2: vendor/roots/acorn/src/Roots/Acorn/Assets/Vite.php 第 917 行附近 — 绕过全局 asset() 函数的覆盖。
把 patch 文件存到 patches/，写个 reapply.sh 在 composer update 后重新打。我已经在文章底部 memory/2026-08-17-wptheme.md 记录了详细步骤。
总结
这套工具链在性能、DX、维护性上都比传统 WordPress 主题开发好得多。Vite 8 + Tailwind 4 + Blade 让你的主题代码更接近现代前端项目结构，但保留 WordPress 生态的所有好处（hooks、plugin、admin UI）。
下一篇会讲怎么用这套栈做主题设置面板（自研 Settings API + Acorn View Composer）。