ideasonpurpose/wordpress

使用Docker进行WordPress本地开发

版本 1.9.3 - WordPress 6.9.4

关于本项目

本项目提供用于快速迭代现有WordPress网站的本地开发环境，包含预配置的基于Docker的MySQL和PHP服务器、https://github.com/ideasonpurpose/docker-build、Xdebug、ImageMagick以及多个辅助脚本。

该项目基于官方WordPress镜像构建，当前版本为**https://hub.docker.com/_/wordpress**%E3%80%82

快速开始

要更新现有项目或启动新项目，请在工作目录中运行以下命令。

macOS、Linux及Windows PowerShell

docker run --rm -it -v ${PWD}:/usr/src/site ideasonpurpose/wordpress:6.9.4 init

然后运行：

npm run bootstrap

注意：如果~/.composer目录不存在，挂载Docker卷时会以root权限创建该目录，可能导致Composer任务失败。请在运行npm run bootstrap前创建该目录，或通过sudo chown -R $UID:$GID .composer重置权限后重新运行bootstrap。详见https://github.com/ideasonpurpose/docker-wordpress-dev/issues/21%E3%80%82

Windows命令提示符

docker run --rm -it -v %cd%:/usr/src/site ideasonpurpose/wordpress:6.9.4 init

• init命令会复制所有必要的工具文件并设置默认主题目录结构。
• npm run bootstrap通过安装npm和composer依赖并重新加载数据库来准备环境。

安装与先决条件

需安装Docker和npm（node.js）。开发服务器通过Docker镜像运行，所有工作流命令通过npm脚本调用。

新项目

在空目录中运行init会提示输入新项目名称和描述，然后构建完整环境及基础主题框架。

现有项目

最近更新的项目可运行npm run project:refresh将工具更新至最新版本。

旧项目应手动运行init进行更新。项目需处于Git工作树干净状态，以便轻松回滚不需要的更改。

将更新以下文件：

• Docker-compose文件将更新至最新版本。
• 默认package.json脚本将合并到现有脚本中。
• DevDependencies、Scripts和Prettier属性将复制到现有package.json中。
• 默认composer.json包和元数据将复制到现有composer.json中。
• 从https://gist.github.com/joemaller/4f7518e0d04a82a3ca16%E6%9B%B4%E6%96%B0.gitignore%E3%80%82
• 基础主题文件夹结构将以非破坏性方式刷新，添加缺失文件夹。
• 创建缺失的ideasonpurpose.config.js文件。
• 重置主题目录和已知工具文件的权限。

在调用npm run start前，将数据库快照复制到顶级**_db目录，将所需插件添加到Plugins目录，并将媒体文件镜像到Uploads**目录。

Plugins和Uploads文件夹不应提交到Git，但应从生产站点镜像，以确保本地环境正常工作。

在**.env中配置SSH密钥路径后，可通过npm run pull命令从远程服务器同步数据库、插件和上传文件。.env.sample**文件记录了所需凭据。

数据库

顶级**_db**目录中的所有*.sql文件将按字母顺序执行，后续文件会覆盖先前文件。

工作流与命令

基本开发命令

• npm run start
  启动数据库和PHP服务器，通过devServer代理在http://localhost:8080提供所有内容。监视项目目录中的文件更改，保存时触发重新加载。按control-c停止本地服务器。可通过--port=8080更改默认端口。

• npm version [major|minor|patch]
  递增版本号，然后使用https://github.com/joemaller/version-everything更新项目文件，再调用npm run build生成生产构建，并将所有主题文件压缩为带版本号的可部署zip归档。

其他命令和辅助工具

• bootstrap
  项目启动辅助脚本，安装npm和composer依赖，重新加载MySQL数据库，激活开发主题，并排序package.json文件。

• build - 生成生产就绪的zip归档构建，可直接部署。

• composer
  从Docker中运行composer install。

  • composer:install - 从composer.lock文件安装包
  • composer:require - 添加新包并更新composer.json
  • composer:update - 将composer依赖更新到最新允许版本并重写composer.lock文件

• db:admin - 在localhost:8002启动phpMyAdmin服务器

• db:dump - 将带时间戳的压缩数据库快照写入**_db**目录

• db:pull - pull:db的别名

• db:reload - 删除并从**_db**中最新的转储文件重新加载数据库，然后尝试激活开发主题

• db:shell - 打开开发WordPress数据库的shell

• dev - start的别名

• mariadb、mysql - db:admin的别名

• mariadb-dump、db:dump、mysql:dump、mysqldump - db:dump的别名

• mariadb:reload、mysql:reload - db:reload的别名

• phpmyadmin - db:admin的别名

• project:refresh - 使用最新工具更新项目

• pull
  将数据从远程服务器同步到本地开发环境。不带参数时运行以下子命令：

  • pull:db - 同步最新MySQL转储文件，备份当前开发数据库并重新加载
  • pull:plugins - 从远程同步wp-content/plugins
  • pull:uploads <$YEAR> - 从远程同步当前年份的wp-content/uploads/$YEAR，可通过可选年份参数指定特定年份
  • pull:uploads-all - 从远程同步整个wp-content/uploads目录

• logs:wordpress - 流式输出WordPress debug.log

• wp-cli - 运行wp-cli命令，默认命令重新激活开发主题

macOS上的权限修复

在macOS主机上，修改挂载Docker卷内的权限会在主机上的共享文件添加扩展属性，而非修改实际权限或所有权。在终端中运行ls -la@或xattr -l <file>可查看这些值。扩展属性值前缀为com.docker.grpcfuse，无论Docker使用gRPC FUSE还是VirtioFS（它们都是FUSE）。

从远程服务器拉取数据

npm run pull命令整合多个子命令将远程数据同步到本地开发环境，每个命令也可单独调用。连接信息必须在**.env文件中配置，.env.sample**文件记录了各值的说明。

私钥通过Docker Secrets传递给镜像，在**.env**中通过$SSH_KEY_PATH指向本地私钥。

目前支持从WP Engine和Kinsta*拉取上传文件、插件和数据库转储。

需在项目根目录的.env文件中配置每台机器的连接。新项目需将.env.example重命名为**.env**并更新设置。

重要属性：

• SSH_KEY_PATH
  本地私钥路径。如果已将id_rsa_wpengine.pub密钥上传到WP Engine账户，指向对应的私钥：~/.ssh/id_rsa_wpengine

• SSH_LOGIN
  WP Engine后台的SSH连接字符串，如iop001@iop001.ssh.wpengine.net，格式为${SSH_USER}@${SSH_HOST}。也可单独输入各部分，单独输入项优先于从SSH_CONNECT_STRING提取的组件。

• SSH_USER
  连接服务器的用户账户。

• SSH_HOST
  服务器地址。

• SSH_WP_CONTENT_DIR
  （默认：sites/${SSH_USER}/wp-content） WordPress wp-content文件夹路径，通常与WP_CONTENT_DIR常量匹配。不带尾斜杠，可为相对于SSH用户主目录的路径或绝对路径。

$SSH_LOGIN和$SSH_HOST可从$SSH_LOGIN提取，指定任一值将覆盖$SSH_LOGIN中的对应值。

从Kinsta同步数据库

与WP Engine不同，Kinsta不在站点的wp-content目录中存储定期数据库快照，但允许使用cron。设置基本crontab任务定期备份数据库，以便拉取脚本正常工作。以下示例每小时37分执行备份：

cron
# 每小时转储数据库用于开发镜像
37      *       *       *       *       mysqldump --default-character-set=utf8mb4 -udb_user -pdb_password db_name > ~/public/wp-content/mysql.sql

Kinsta和WP Engine的服务器均不允许请求*.sql文件，且db_user、db_password和db_name已明文存储在wp-config.php中，因此无安全风险。

调试

默认启用WP_DEBUG，可通过在**.env**配置文件中设置WORDPRESS_DEBUG变量切换。

更新WordPress

基础镜像提供特定版本的WordPress，但运行后可通过wp-admin仪表板像其他站点一样升级。

也可使用wp-cli更新到WordPress的预发布版本，示例命令：

sh
npm run wp-cli wp core update https://wordpress.org/wordpress-6.5-RC3.zip

可通过删除Docker *_wp卷回滚版本。

升级镜像版本

npm run bump脚本将查询WordPress发布API和DockerHub，更新docker镜像和README至最新WordPress镜像。

要更新到预发布镜像，在wp-version.json文件中输入有效的DockerHub标签。

插件开发

项目通常依赖并行开发的插件。提供多个占位符IOP_DEV_PLUGIN_#环境变量，可用于将插件直接挂载到WordPress环境。这改善了版本控制和依赖管理，因为嵌套且被.gitignore忽略的wp-content/plugins目录常与父主题冲突。

要将开发插件添加到WordPress环境，将插件的本地相对路径指向容器内的绝对路径。例如，要将同级目录中开发的example-plugin项目提供给当前WordPress开发环境：

   IOP_DEV_PLUGIN_1="../example-plugin:/var/www/html/wp-content/plugins/example-plugin"
   IOP_DEV_PLUGIN_2=
   IOP_DEV_PLUGIN_3=

访问运行中的容器

要在任何运行中的Docker容器上打开shell，运行docker ps获取容器ID或名称，然后运行docker exec -it <名称或ID> bash。部分容器可能使用sh而非bash。要在运行的WordPress实例上打开shell，运行docker-compose exec wordpress bash。

其他composer命令

Composer镜像也可通过docker-compose直接运行其他特定命令：

sh
docker-compose run --rm  composer update
docker-compose run --rm  composer require monolog/monolog

# 在composer镜像中打开shell
docker-compose run --rm  composer bash

使用备用端口

所有提供服务器的服务可通过--port=标志自定义默认端口，允许在同一台计算机上同时运行多个项目。

sh
# 站点一
npm run start --port=8080

# 站点二
npm run start --port=8081

默认端口

• webpack devserver: 8080
• phpMyAdmin: 8002
• WebGrind: 9004

phpinfo()

PHP信息页面可通过localhost:8080/info.php访问。

调试与分析

要使用XDebug和https://github.com/jokkedk/webgrind分析请求，在任何请求后添加?XDEBUG_PROFILE=1。将在webpack/xdebug中创建cachegrind.out.nn文件。运行npm run webgrind将启动WebGrind服务器查看这些文件，默认地址为http://localhost:9004，可通过npm run webgrind --port=9123更改端口。

阅读调用图

每个分析运行也可视为调用图，这些图在https://github.com/jrfonseca/gprof2dot#output%E4%B8%AD%E6%9C%89%E6%96%87%E6%A1%A3%E8%AF%B4%E6%98%8E%EF%BC%9A

+------------------------------+
|        函数名称              |
| 总时间% (自身时间%)          |
|         总调用次数           |
+------------------------------+

其中：

• 总时间%：在该函数及其所有子函数中花费的运行时间百分比；
• 自身时间%：仅在该函数中花费的运行时间百分比；
• 总调用次数：该函数被调用的总次数（包括递归调用）。

wp-cli

默认命令替换wp前缀，因此其他命令格式如下：

• npm run wp-cli transient delete --all
• npm run wp-cli user list

wp-cli命令参考

本地开发

要在本地迭代此项目，使用与Docker Hub远程相同的名称构建镜像，Docker将使用本地副本。如果使用版本，指定dev标签：

sh
docker build . --tag ideasonpurpose/wordpress:dev

Shell脚本

bin中的所有shell脚本均已通过ShellCheck检查，并使用https://github.com/mvdan/sh%E6%A0%BC%E5%BC%8F%E5%8C%96%EF%BC%8C%E5%91%BD%E4%BB%A4%EF%BC%9A%60npm run shfmt`。

Docker维护

以下是一些有用的Docker命令，虽不特定于本项目，但有助于保持Docker正常运行：

• docker-compose down - 停止并删除容器
• docker system prune - 清理未使用的容器和镜像
• docker system prune -a - 清理所有内容，需重新下载资源
• docker ps - 列出运行中的容器
• docker exec -it <容器> bash - 在运行中的容器上打开shell

附加说明

基础WordPress docker镜像中的docker-entrypoint.sh脚本通过检查index.php和wp-includes/version.php来判断WordPress是否已安装。

由IOP提供

本项目由 Ideas On Purpose 积极开发并在生产环境中使用。