环境搭建

这一课你将能做到

1. 用 Docker 独立搭起一套 WP 6.x + PHP 8.2 + MySQL 8 的本地环境（并知道 Local 方案的取舍）
2. 完成五分钟安装，读懂 wp-config.php 里每一行关键配置
3. 用 WP-CLI 完成首次「体检」：查版本、列插件、看用户

为什么要学

所有后续课程都跑在这一课的环境上。更重要的是：会装只是起点，读懂 wp-config.php 和目录结构，你才能排查白屏、配置调试、控制数据库——生产事故的第一现场全在这里。

人话：这课相当于拿到新房钥匙后先摸清水电总闸在哪。总闸都找不到，后面装修全靠猜。

先建立图像

你的请求 http://localhost:8080
   ↓
容器 wordpress (PHP 8.2 + Apache + WP 6.x)   ← 读 /var/www/html
   ↓ 连接 db:3306（注意不是 localhost!）
容器 db (MySQL 8)  ← 数据落在命名卷 wpdb_data
   ↓
浏览器看到安装向导 / 首页

关键认知：容器之间用「服务名」通信。WP 容器里连数据库要写 db，写 localhost 会连到 WP 容器自己——这是初学者报「数据库连接错误」的头号原因。

跟着做

步骤 1：Docker Compose 一键起环境

新建目录 wp-lab，在其中创建 docker-compose.yml：

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wpuser
      MYSQL_PASSWORD: wppass
    volumes:
      - wpdb_data:/var/lib/mysql
  wordpress:
    image: wordpress:6-php8.2-apache
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db        # 服务名，不是 localhost
      WORDPRESS_DB_USER: wpuser
      WORDPRESS_DB_PASSWORD: wppass
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html     # 之后主题插件在这里
volumes:
  wpdb_data:
  wp_data:

执行：

docker compose up -d

浏览器打开 http://localhost:8080。

步骤 2：完成五分钟安装

安装向导选「简体中文」→ 填站点标题 → 设管理员账号密码（本地随便，生产必须强密码）→ 安装。完成后登录 /wp-admin/。

不想用 Docker：装 Local（原 LocalWP）图形化一键建站，自带 PHP 版本切换与邮件捕获，适合怕命令行的初学者。本课程代码两种环境通用。

步骤 3：读懂 wp-config.php

进入 WP 容器查看配置：

docker compose exec wordpress bash
cat /var/www/html/wp-config.php

重点行解读：

define( 'DB_NAME', 'wordpress' );      // 库名
define( 'DB_USER', 'wpuser' );         // 数据库用户
define( 'DB_PASSWORD', 'wppass' );     // 密码
define( 'DB_HOST', 'db' );             // 主机：容器里是服务名
$table_prefix = 'wp_';                 // 表前缀，多站共用一库时用于隔离
define( 'WP_DEBUG', false );           // 调试总开关，本地开发改 true

在 /* Add any custom values */ 注释下方追加（本地调试三件套）：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );    // 错误写入 wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // 不直接输出到页面

步骤 4：安装 WP-CLI 并做首次体检

WP-CLI 是官方命令行工具。容器内已有：

docker compose exec wordpress wp core version   # 输出 6.x
docker compose exec wordpress wp plugin list --format=table
docker compose exec wordpress wp user list
docker compose exec wordpress wp config get WP_DEBUG

也可以独立安装到宿主机。这四个命令请形成肌肉记忆——以后排查任何 WP 问题，先跑一遍它们建立现场认知。

步骤 5：认清目录结构，划出「雷区」

/var/www/html/
├── wp-admin/        ← 后台程序，只读，永远不改
├── wp-includes/     ← 核心函数库，只读，永远不改
├── wp-content/      ← 唯一属于你的世界
│   ├── themes/      ← 主题（第 3 课起）
│   ├── plugins/     ← 插件（第 5 课起）
│   ├── uploads/     ← 媒体文件
│   └── debug.log    ← 调试日志
└── wp-config.php    ← 全站最敏感文件（含数据库密码）

讲清楚要点

1. 只动 wp-content 和 wp-config.php：直接改 wp-includes 里的核心文件，升级即丢，且是安全审计红线。
2. 为什么 WP 6.x 要求 PHP 8.2+：性能（JIT、只读属性、枚举）、安全（8.1 以下已陆续停止安全维护）、以及新代码可以写现代 PHP。
3. 调试开关的纪律：WP_DEBUG=true + WP_DEBUG_DISPLAY=false + 日志落盘，是本地标准姿势；生产环境 WP_DEBUG 必须为 false。
4. 数据在卷里，容器随时可扔：docker compose down 容器销毁但 wpdb_data 卷还在，数据不丢——这是理解「有状态服务」的最小案例。

你可能会懵的地方

• Local、Docker、宝塔怎么选？ 只写主题插件选 Local 最快；要模拟生产、配 Nginx/Redis 或团队统一环境选 Docker；宝塔适合直接管生产 VPS，不建议当本地开发工具。

• WP_DEBUG 上线要不要关？ 必须。调试信息可能泄露路径、SQL 与配置。上线的正确姿势是 WP_DEBUG false，问题靠日志和监控查（第 11 课）。

• wp-content 能改名吗？ 能（WP_CONTENT_DIR/URL 两个常量），但会破坏大量按默认路径写的插件兼容性，收益仅是隐蔽，不建议。

• 报「Error establishing a database connection」怎么排查？ 按 DB_NAME → DB_USER → DB_PASSWORD → DB_HOST 顺序核对；容器环境 90% 是 DB_HOST 写了 localhost。

• 端口 8080 被占了？ 改 compose 里 "8081:80" 即可，容器内部 80 不用动。

错法对照

错法	问题	正解
DB_HOST 写 localhost（容器内）	连进 WP 容器自身，必然失败	写 compose 服务名 db
数据库密码提交进 git	密钥泄露	本地用示例值，生产走环境变量
修改 wp-includes 源文件	升级覆盖 + 留后门风险	用插件/主题的钩子扩展
WP_DEBUG_DISPLAY=true 长期开着	页面暴露报错细节	改用 WP_DEBUG_LOG + 看日志
用记事本编辑 PHP 文件	BOM 头导致 headers already sent	用 VS Code，保存为 UTF-8（无 BOM）

卡点急救

1. 整站白屏：wp-content/debug.log 看最后几行；八成是刚改过的 functions.php 或插件语法错误，回滚该文件即可。
2. 安装卡在数据库一步：容器环境先确认 db 容器 docker compose ps 状态是 healthy/running，再核对 DB_HOST。
3. wp 命令找不到：容器内用 docker compose exec wordpress wp ...；宿主机装 WP-CLI 后确认 phar 文件有执行权限并加入 PATH。

面试常问

• WordPress 的目录结构中哪些是可以修改的？ 只应修改 wp-content（主题、插件、上传）与 wp-config.php；wp-admin/wp-includes 属于核心，升级会覆盖，改动它们是反模式。

• wp-config.php 里你一定会配的项有哪些？ 数据库四项连接信息、表前缀、AUTH_KEY 等 8 个盐值（用于 Cookie 加密）、调试开关，生产环境还会加 Redis 对象缓存与强制 SSL 常量。

• 如何安全地在本地开启调试？ WP_DEBUG true、WP_DEBUG_LOG true、WP_DEBUG_DISPLAY false，错误进 wp-content/debug.log，排查完即关闭。

自测三问

1. 容器化部署时，WP 连接数据库的主机名为什么不是 localhost？
2. wp-config.php 中 table_prefix 的作用是什么？
3. 写出本地调试三常量的标准组合及各自含义。

小结一句话

用 Docker（或 Local）把 WP 6.x + PHP 8.2 + MySQL 8 跑起来只是开始，读懂 wp-config.php、认清目录雷区、让 WP-CLI 成为肌肉记忆，才算真正「接管」了一个 WordPress 站点。

延伸

• 官方安装与准备文档
• WP-CLI 官网与命令手册
• 下一课：主题体系——模板层级、开箱主题与子主题的正确打开方式。