TL;DR​

Chrome 扩展在开发调试时，每次测试采集都会把数据写进生产数据库。用三层 DRY-RUN 开关解决：.env.development 设环境变量 → 客户端读取后给请求加 X-Dry-Run Header → 服务端拦截该 Header 返回数据预览，不执行写入。生产环境不设该变量，完全不受影响。

TL;DR​

Chrome 扩展使用 sidepanel 作为 UI 入口，用户登录后 token 存入 localStorage。但 Service Worker（background script）没有 localStorage，调用直接抛 ReferenceError。解决方案：sidepanel 登录后通过 chrome.runtime.sendMessage 将 token 同步给 Service Worker，由 Service Worker 写入 chrome.storage.local。两边各取所需——sidepanel 读 localStorage，Service Worker 读 chrome.storage.local。

TL;DR​

WSL2 + Docker Desktop 有两个常见的网络坑：

1. 端口被静默占用：Docker 容器映射 5432 后，SSH 隧道 localhost:5432 连到的是容器内的 PostgreSQL 而非远程服务器——密码没错，连的实例错了
2. host 模式 localhost 不通：network_mode: host 共享的是 Docker 工具 VM 网络，不是 WSL2 网络——curl localhost:8080 失败

在为客户搭建 AI 数据分析平台（Airflow + PostgreSQL）的本地开发环境时遇到此问题，记录根因与解法。

TL;DR​

Docker Desktop for Windows (WSL2 backend) 下，network_mode: host 的容器端口无法从 WSL2 宿主机访问。容器内 ss 显示端口在监听，但宿主机 curl localhost:PORT connection refused。原因是 host 模式共享的是 Docker 内部工具 VM 的网络，不是 WSL2 的网络。解法：override 文件中用 network_mode: !reset 移除 host 模式，改用 bridge + external network + 端口映射。

在为客户开发 WordPress Block Theme 时反复遇到这五个问题，每次排查都花了不少时间。整理成指南，帮助同样在做 FSE 开发的同学快速定位。

TL;DR​

五个问题按频率排序：文件修改不生效（数据库缓存覆盖文件）、块嵌套错乱（注释未关闭）、子主题内容不渲染（缺少 post-content 块）、SVG 图标消失（WP_Filesystem 被插件污染）、WP-CLI 邮件失败（SMTP 插件在命令行不生效）。每个场景都给出可直接复用的排查命令。

在为客户构建 WooCommerce Block Theme 时遇到了这四个与 WooCommerce 相关的问题，每个都与 FSE 架构和 WooCommerce 的块系统有关。记录排查过程，帮助同样在做 WooCommerce 主题开发的同学避坑。

TL;DR​

四个 WooCommerce Block Theme 开发中的常见问题：块重命名导致 core/missing（升级后块名加了 -block 后缀）、修改 shop slug 后产品归档 404（rewrite 缓存未刷新）、模板 HTML 与 Gutenberg save 不匹配（动态块验证失败）、Cart/Checkout 模板未自动分配（需要手动指定）。每个场景给出可直接复用的修复方案。

TL;DR​

在 SITE123 平台的活动页面嵌入时间轴，踩了 5 类坑：Custom Code 无法精准定位、脚本在 DOM 未加载时执行、选择器命中 隐藏元素、float 布局冲突导致相邻区块错位、平台缓存造成 脚本重复注入。解决方案：JS 动态 DOM 操作 + 横向鱼骨布局 + DOMContentLoaded 包裹。

在为客户部署 WordPress 站点时遇到此问题，记录根因与解法。

TL;DR​

镜像 Dockerfile 中的 VOLUME 声明会创建匿名卷，挂载优先级高于 docker-compose.yml 的 bind mount。解决方案：停止容器 → 删除匿名卷 → 重启。

在为客户开发 WordPress 主题时遇到此问题，记录根因与解法。

TL;DR​

WordPress 主题的导航滚动变色功能（.is-scrolled 类）在停用 WooCommerce 插件后失效。排查发现是 Query Monitor 插件的 action_print_footer_scripts 回调优先级 9999 太低，提前执行并终止了所有 footer scripts 输出。删除 Query Monitor 后问题解决。

在 WSL2 环境下使用 Claude Code、Roo 等 AI 编程工具时，工具需要通过 Windows 宿主机代理访问 API，却反复报 ConnectionRefused。解决防火墙问题后，又遇到两个隐藏坑。记录完整排查过程。

TL;DR​

WSL2 的 vEthernet (WSL) 虚拟网卡每次启动重建，Windows 防火墙无法为其分配 Network Profile，导致所有入站规则对这个接口都不生效（EnforcementStatus: NotApplicable）。不需要加规则，直接对接口禁用防火墙即可：

# 在 Windows PowerShell (管理员) 中执行
Set-NetFirewallProfile -DisabledInterfaceAliases "vEthernet (WSL)"

此外，修复防火墙后，还可能遇到两个额外坑：

1. 动态 IP 问题：宿主机 IP 在 WSL/Windows 重启后变化
2. 配置缓存问题：~/.claude.json 和 ~/.claude/settings.json 里缓存了旧 API key 导致认证冲突