WordPress 项目的 .gitignore 怎么写：该忽略什么、绝不能忽略什么

引言：两种极端，都很痛

我见过两种 WordPress 仓库：

一种是”什么都提交”——wp-content/uploads 里几千张图全进 Git，clone 一次二十分钟，.git 目录比站点还大；

另一种是”什么都不懂就照抄别人的 ignore”——结果子主题、自定义插件、配置文件全被忽略，换台机器 clone 下来是个空壳，站点根本起不来。

写 .gitignore 的判断标准只有一条：这个文件是不是”代码”？ 是代码就提交，是运行时产生的数据或含密钥的配置就忽略。

原理分析：WordPress 目录里都有什么东西

保姆级实操：完整模板

# ---------- 核心：如果用 Composer 管理则忽略 ----------
/wp/
/wp-admin/
/wp-includes/
/index.php
/license.txt
/readme.html
/wp-activate.php
/wp-blog-header.php
/wp-comments-post.php
/wp-config-sample.php
/wp-cron.php
/wp-links-opml.php
/wp-load.php
/wp-login.php
/wp-mail.php
/wp-settings.php
/wp-signup.php
/wp-trackback.php
/xmlrpc.php

# ---------- 配置：含密钥，绝不提交 ----------
wp-config.php
wp-config-local.php
.env
.env.*
!.env.example

# ---------- 上传与运行时数据 ----------
/wp-content/uploads/
/wp-content/cache/
/wp-content/upgrade/
/wp-content/backup-db/
/wp-content/backups/
/wp-content/wflogs/
/wp-content/aiowps_backups/
/wp-content/ngg/
*.log
*.sql
*.sql.gz
*.tar.gz

# ---------- 第三方依赖 ----------
/vendor/
node_modules/
/wp-content/plugins/*
/wp-content/themes/twenty*
/wp-content/mu-plugins/*

# ---------- 但保留自研代码 ----------
!/wp-content/plugins/my-*
!/wp-content/plugins/mmf-*
!/wp-content/themes/lumen-mimangfei/
!/wp-content/themes/lumen-mimangfei-child/
!/wp-content/mu-plugins/mmf-*
!/wp-content/mu-plugins/*.php

# ---------- 缓存与调试产物 ----------
.cache/
advanced-cache.php
object-cache.php
db.php
/debug.log
.error.log

# ---------- 系统与编辑器 ----------
.DS_Store
Thumbs.db
.idea/
.vscode/
*.swp
*~

关键技巧：反向保留（negation）

!/wp-content/themes/lumen-mimangfei/ 这类以 ! 开头的规则叫”反向保留”，必须写在忽略规则之后，否则不生效：

/wp-content/themes/*            # 先忽略全部主题
!/wp-content/themes/my-theme/   # 再放行自己的主题

注意第一行写的是 /* 而不是 /，后者会把目录本身排除，导致后面的 ! 规则失效——这是最常见的坑。

必须提交但常被忽略的三样

1. composer.lock —— 锁定依赖版本， reproducibility 的保证；
2. wp-config-sample.php 改造的模板（如 wp-config.example.php）—— 让新同事知道要配哪些常量；
3. 数据库结构变更脚本或迁移脚本。

安全自查：提交前扫描密钥

grep -rInE "(DB_PASSWORD|AKIA[0-9A-Z]{16}|sk_live_|AIza[0-9A-Za-z_-]{20})" . --exclude-dir=.git | head

已经提交过密钥的话，光改文件没用，密钥仍在历史里。要用 git filter-repo 清理历史并立即轮换密钥。

常见踩坑与失败案例

1. 提交了 uploads 后想删 —— git rm --cached 只会从后续提交移除，历史里的文件还在。必须先加 ignore，再用 git filter-repo 清历史，然后 git gc。
2. .gitignore 不生效 —— 文件已经被 tracked 了。要先 git rm --cached <文件> 再提交。
3. 案例：某团队把 wp-config.php 提交到了私有仓库，仓库后来被误设为公开，数据库账号密码泄露。正确做法是提交 wp-config.example.php，真实配置走 .env 或部署时注入。
4. 忽略 object-cache.php 导致缓存插件失效 —— Redis 对象缓存的 drop-in 文件在 wp-content/ 根目录，如果被忽略，部署后对象缓存静默失效。应改为由部署脚本生成。
5. Windows 换行符导致 diff 爆炸 —— 加 .gitattributes：* text=auto eol=lf。

总结

写 WordPress 的 .gitignore，本质上是在回答”哪些是我要维护的资产”。我的判断顺序是：先忽略核心与第三方（用 Composer 还原）、再忽略数据与密钥、最后用 ! 放行自研主题插件和 mu-plugins。写完用 git status --ignored 复核一次，确认自研代码没被误伤、密钥没被带进去，就可以放心提交了。