Sage 11 + Acorn 5 主题开发：从零到第一个 Hello World
这篇教程带你完整搭建一个 Sage 11 主题，最终能跑通：
- Vite 8 + Tailwind 4 + Blade 模板
- Composer + npm 双包管理
- 主题激活后能正常显示「Hello World」
前置环境
# Linux (Ubuntu 22.04)
php -v # 8.1+
node -v # 20+
npm -v # 10+
composer --version
mysql --version # 5.7+ / 8.0+
Sage 11 最低要求 PHP 8.1，建议 PHP 8.2。我自己用 8.2 跑得很稳。
创建 WordPress 站点
如果还没有 WP 站点，先装一个。最快的方式用 BT 面板（或者手动装 LNMP）。
手动装的话：
# 1. 下载 WordPress
cd /www/wwwroot/
wget https://wordpress.org/latest.tar.gz
tar xzf latest.tar.gz
mv wordpress your-site.com
2. 创建数据库
mysql -uroot -p
CREATE DATABASE wp_yoursite DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wp_user'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD';
GRANT ALL ON wp_yoursite. TO 'wp_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
3. 配置 wp-config.php
cd your-site.com
cp wp-config-sample.php wp-config.php
修改 DB_NAME, DB_USER, DB_PASSWORD
访问 https://your-site.com 完成安装向导
安装 Sage 11 主题
Sage 11 用 Composer 创建项目，会自动把所有 PHP 依赖装好：
cd /www/wwwroot/your-site.com/wp-content/themes/
composer create-project roots/sage your-theme-name
cd your-theme-name
npm install
这一步会装：
roots/sage主包roots/acornLaravel 容器（5.0.0-beta.2）illuminate/Laravel 组件composer/installers让 vendor 装到正确位置
第一次启动 Vite 开发服务器
npm run dev
你会看到 Vite 输出：
VITE v8.x.x ready in xxx ms
➜ Local: http://localhost:5173/
➜ Network: http://your-ip:5173/
但 Vite 开发服务器在生产站点下访问不到。Sage 11 的设计是：开发时用 Vite HMR，生产时 build 到 public/build/ 然后让 nginx 服务。
配置 nginx（生产模式）
在 /www/server/panel/vhost/nginx/your-site.com.conf 加一段：
# Sage 11 build assets 路由
location ^~ /app/themes/your-theme-name/public/build/ {
expires 30d;
add_header Cache-Control "public, max-age=2592000";
access_log off;
}
第一个生产构建
npm run build
输出：
public/build/
├── manifest.json
├── assets/
│ ├── app-XXX.css # 主样式
│ ├── app-XXX.js # 主脚本
│ └── theme.json # Tailwind 主题变量
激活主题
进 wp-admin → 外观 → 主题，启用「旅买爱 LVmaai Theme」（或你的主题名）。
激活后访问首页，你应该能看到默认的「Hello World」。
Acorn 5 vendor patch（重要）
Acorn 5.0.0-beta.2 跟 Vite 8 不兼容，必须打 patch。我之前踩过这两个坑：
Patch 1: Manifest 格式兼容
vendor/roots/acorn/src/Roots/Acorn/Assets/Manifest.php 第 47 行：
$value = $manifest[$key] ?? null;
if (is_array($value)) {
$value = (object) $value;
}
Vite 8 的 manifest 把所有值都包成对象，原版代码会失败。
Patch 2: asset() 函数覆盖绕过
vendor/roots/acorn/src/Roots/Acorn/Assets/Vite.php 第 917 行附近。如果你的 globals.php 重定义了 asset() 函数，会让 Acorn 拿不到 Asset 对象（返回字符串）。
详细的 patch 文件和 reapply 脚本都存在 patches/ 目录：
bash patches/reapply.sh # 在 composer update 后跑
验证一切正常
进 wp-admin → 主题设置 → 检查 47 个字段是否都能保存。
自研设置面板示例
Sage 默认没设置面板，但 Acorn 让我们能用 WordPress Settings API + Blade 自研一个。这是阶段 2 的核心工作，代码量约 600 行。
简单说就是：
// app/Settings/SettingsPage.php
public static function register(): void {
add_action('admin_menu', [self::class, 'addMenu']);
add_action('admin_init', [self::class, 'registerSettings']);
}
public static function schema(): array {
return [
'branding' => [
'title' => '品牌 & 视觉',
'fields' => [
['key' => 'logo_id', 'label' => '站点 Logo', 'type' => 'image'],
['key' => 'primary_color', 'label' => '主色', 'type' => 'color'],
],
],
// ...
];
}
然后用 View Composer 注入到所有前台 Blade 视图：
// app/View/Composers/Settings.php
protected static $views = ['*'];
public function with(): array {
return \App\Settings\Options::all();
}
这样所有 Blade 文件都能用 $logoUrl、$primaryColor 等变量。
调试技巧
1. Acorn 缓存卡住
如果改完代码页面没生效：
wp acorn optimize:clear
/etc/init.d/php-fpm-82 reload
2. Blade 编译报错
打开 WP_DEBUG_LOG 看具体错误：
// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false); // 关键：不要 true，否则 warning 会变 500
3. Vite manifest 找不到
每次 build 后必须同步 manifest：
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/ resources/
总结
Sage 11 + Acorn 5 是目前 WordPress 主题开发的最佳现代栈。配合 Vite 8 + Tailwind 4，开发体验接近 Laravel/Vue 项目，但保留 WordPress 生态的所有好处。
接下来你可以做：
- 阶段 3：自定义文章类型（CPT）+ Meta Box
- 阶段 4：主题设置面板
- 阶段 5：会员/付费
- 阶段 6：API + Headless
下一篇讲 Vite 8 在 WordPress 主题里的配置优化。