本文约 4,695 字，预计阅读 12 分钟。文中命令与配置均经过实测，可直接参考执行。
引言：写第一行代码之前，先卡在环境上
主题开发的新手常在这几步耗掉一整天：PHP 版本不对导致白屏、Node 版本太旧装不上依赖、Sage 跑 composer install 报缺扩展、改了 SCSS 但前台没变化（因为忘了开 watch）。环境本身不是目的，但它决定了你后面每一次「保存—刷新」的顺畅程度。
三条主流起步路线各有各的环境要求：Underscores（_s）最轻，只需要一个能跑 WordPress 的环境和一个 Sass 编译器；Sage（Roots）要求 PHP 8、Composer、Node 与 Bud 构建链，学习曲线陡但工程化最强；Timber 介于两者之间，只要能装 Composer 包或插件就能用 Twig。选哪条，取决于你的项目是「交付一个简单企业站」还是「长期维护的产品级主题」。
原理分析：三条路线的技术栈差异
| 路线 | 技术栈 | 环境依赖 | 适合 |
|---|---|---|---|
| Underscores（_s） | 原生 PHP 模板 + Sass | PHP/MySQL + Sass | 入门、轻量定制、上架官方目录 |
| Timber | PHP 控制器 + Twig 模板 | PHP + Composer（或插件） | 模板逻辑复杂、想分离 PHP 与 HTML |
| Sage | Blade 模板 + Bud 构建 + Acorn | PHP 8+ + Composer + Node 18+ | 团队项目、需要现代前端工程化 |
本地环境本身的选择（Local、wp-env、DevKinsta、Docker、XAMPP）与主题路线是正交的：任何一条路线都能跑在任何一个环境上。差别只在「你能不能开命令行」——Sage 和 Timber 强烈依赖命令行（Composer、npm），图形化工具（如 XAMPP）虽然能跑 WordPress，但跑构建链会很别扭。
推荐组合：命令行熟手用 wp-env（官方，基于 Docker，一条命令起站）；想要图形界面用 Local（LocalWP，Windows/macOS 都有，支持一键切 PHP 版本与 SSL）；团队统一环境用 Docker Compose 写死配置。
保姆级实操
第一步：用 wp-env 起一个本地站（推荐）
npm -g install @wordpress/env
mkdir -p ~/wp-dev/mimangfei && cd ~/wp-dev/mimangfei
新建 .wp-env.json：
{
"core": "WordPress/WordPress#6.8",
"themes": [ "." ],
"plugins": [
"https://downloads.wordpress.org/plugin/woocommerce.zip",
"https://downloads.wordpress.org/plugin/theme-check.zip"
],
"port": 8888,
"config": {
"WP_DEBUG": true,
"WP_DEBUG_DISPLAY": true,
"SCRIPT_DEBUG": true
}
}
启动与常用命令：
wp-env start
wp-env run cli wp theme list
wp-env run cli wp rewrite structure '/%postname%/' --hard
wp-env stop --script=stop
themes: [ "." ] 会把当前目录挂载为主题目录，配合 wp-env run cli wp theme activate 即可激活开发中的主题。
第二步：Underscores 路线（最轻）
cd ~/wp-dev/mimangfei
wp-env run cli wp scaffold _s mimangfei --theme_name="迷忙飞主题" --author="迷忙飞" --activate
编译 SCSS（任选其一，_s 自带 package.json 时优先用它的 scripts）：
npx sass sass/style.scss style.css --watch
环境要求只有 PHP 7.4+ / MySQL 5.7+，任何本地环境都能跑。适合刚起步或要上架官方目录的主题。
第三步：Timber 路线（Twig 模板）
最快的方式是装插件：
wp-env run cli wp plugin install timber --activate
或用 Composer 管理（版本更可控，适合团队协作）：
composer require timber/timber
functions.php 引入自动加载：
require_once __DIR__ . '/vendor/autoload.php';
之后模板就能用 Timber::render() 了（详见 Timber + Twig 做主题）。环境要求：PHP 7.4+（Timber 2.x 建议 8.0+），Composer 2。
第四步：Sage 路线（工程化最重）
composer create-project roots/sage mimangfei-sage
cd mimangfei-sage
composer install
npm install
npm run dev
Sage 10 使用 Bud 做构建（npm run dev 起开发服务器、npm run build 出生产包），模板是 Blade（.blade.php），底层由 Acorn 提供 Laravel 组件。环境要求：PHP 8.1+、Composer 2、Node 18+。
常见的环境报错与处理：
# 缺 PHP 扩展时 Composer 会明确提示，例如
composer install
# → "Your requirements could not be resolved: ext-fileinfo is missing"
# 在 php.ini 里启用对应扩展后重试
php -m | grep -E 'fileinfo|mbstring|intl'
第五步：Docker Compose 团队统一环境
version: '3.8'
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: localdev
MYSQL_DATABASE: wordpress
volumes:
- db_data:/var/lib/mysql
wordpress:
image: wordpress:php8.2-apache
ports:
- "8080:80"
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_NAME: wordpress
WORDPRESS_DB_USER: root
WORDPRESS_DB_PASSWORD: localdev
WORDPRESS_DEBUG: 1
volumes:
- ./wp-content:/var/www/html/wp-content
volumes:
db_data:
只挂载 wp-content，核心由镜像提供，升级只需换镜像 tag。注意这里只是本地开发用，不要把这类配置直接搬到生产。
第六步：把调试环境配好
wp-config.php（或 wp-env 的 config）里：
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
define( 'WP_ENVIRONMENT_TYPE', 'development' );
再装 Query Monitor 看慢查询与钩子耗时：
wp-env run cli wp plugin install query-monitor --activate
常见踩坑
- PHP 版本不匹配：Sage 10 在 PHP 7.4 上直接报语法错误，装之前先
php -v确认。 - Node 版本过旧：Bud/Vite 要求 Node 18+，用
node -v检查，Windows 上建议用 nvm-windows 管理多版本。 - 改了 SCSS 前台没变：忘记开
--watch，或浏览器缓存了旧的 style.css，加版本号（wp_get_theme()->get('Version')）能缓解。 - Docker 卷挂载导致权限问题：Windows 下
wp-content挂载后文件属主不对，容器内无法写入，改用 WSL2 后端可解决。 - MySQL 8 认证方式不兼容：老版 PHP 连 MySQL 8 报
The server requested authentication method unknown to the client，改用mysql:5.7镜像或改用户的认证插件。 - 案例：某团队用 XAMPP 做 Sage 开发，PHP 是 7.4、没有 Composer，硬装后 Acorn 启动报
Call to undefined function，折腾两天没跑起来。后来统一切到 Docker Compose 固定 PHP 8.2 镜像，每人docker compose up一条命令起站，后续再也没有「我这儿能跑你那儿不行」的问题。 - 把本地调试配置提交到仓库：
wp-config.php里写死本地数据库信息，别人拉取后连不上，应改为环境变量或.env（并加入.gitignore）。 - 忘了刷新固定链接：新建自定义文章类型后归档页 404，
wp rewrite flush一下就好，且别把它写进每次加载的代码里。
总结
选择建议：第一次做主题——Underscores + 任意本地环境，先把模板层级和钩子跑通；模板逻辑复杂、想让 PHP 与 HTML 分离——Timber，成本低于 Sage；团队长期维护、需要现代构建链——Sage，但要接受它的学习成本与环境要求。环境搭建的目标只有一个：让「改一行代码 → 刷新看到结果」在两秒内完成。做到这一点之后，再按 用 Underscores 从零做主题 的流程推进，或用 Tailwind 与 WordPress 主题结合 的方案接上前端构建。
