# 插件冲突

插件冲突是 WCPOS 问题最常见的原因之一。当其他 WordPress 插件干扰 WooCommerce 或 WCPOS 功能时，您可能会遇到崩溃、性能问题或意外行为。

## 插件冲突的迹象[​](#signs-of-plugin-conflicts "直接链接到 插件冲突的迹象")

如果您遇到以下情况，可能存在插件冲突：

* **致命错误** - “该网站出现了严重错误”
* **性能问题** - 加载缓慢、超时或服务器负载高
* **功能问题** - 功能未按预期工作
* **数据同步问题** - 产品、订单或客户未正确同步
* **支付网关问题** - 结账失败或支付处理错误

## 开始之前：使用暂存网站[​](#before-you-start-use-a-staging-site "直接链接到 开始之前：使用暂存网站")

重要

**绝不要在您的生产网站上故障排除插件冲突。** 始终使用暂存环境，以避免干扰您的业务运营。

### 什么是暂存网站？[​](#what-is-a-staging-site "直接链接到 什么是暂存网站？")

暂存网站是您现场网站的精确副本，您可以安全地测试更改，而不影响客户。大多数现代主机提供商都将暂存环境作为标准功能。

### 如果您的主机不提供暂存[​](#if-your-host-doesnt-offer-staging "直接链接到 如果您的主机不提供暂存")

如果您的托管提供商不提供暂存网站，**考虑切换到提供此服务的主机**。这在现在是一个标准功能，对于以下情况至关重要：

* 安全的插件/主题测试
* WordPress 更新
* 故障排除问题
* 开发工作

**推荐具有暂存功能的主机：**

* WP Engine
* SiteGround
* Kinsta
* Cloudways
* 其他许多

## 第 1 步：检查致命错误[​](#step-1-check-for-fatal-errors "直接链接到 第 1 步：检查致命错误")

如果您遇到崩溃或严重错误，请首先检查错误日志：

1. **检查 WCPOS 日志** - 打开 WCPOS 中的[日志](/zh-CN/support/logs.md)屏幕以查找任何错误消息
2. **检查致命错误日志** - 请按照[致命错误故障排除指南](/zh-CN/support/troubleshooting/critical-error.md)找到详细的错误消息
3. **记录错误详情** - 查找错误中提到的插件名称或文件路径

如果您发现提到特定插件的致命错误，那可能就是罪魁祸首。您可以禁用该插件并检查问题是否已解决。

## 第 2 步：插件消除法[​](#step-2-the-plugin-elimination-method "直接链接到 第 2 步：插件消除法")

如果日志中没有致命错误，或者您想识别与性能相关的冲突，请使用此系统化的方法：

### 2.1 创建基线[​](#21-create-a-baseline "直接链接到 2.1 创建基线")

1. **访问您的暂存网站**
2. **测试有问题的功能** - 记录确切无法工作或运行缓慢的内容
3. **记录性能指标** - 如果是性能问题，请记录来自[日志](/zh-CN/support/logs.md)的执行时间

### 2.2 禁用所有插件（除必要插件外）[​](#22-disable-all-plugins-except-essential-ones "直接链接到 2.2 禁用所有插件（除必要插件外）")

**保持以下插件处于活动状态：**

* WooCommerce
* WCPOS
* WCPOS Pro（如果您拥有）

**禁用其他所有插件：**

1. 转到 `WP Admin > Plugins`
2. 选择所有其他插件
3. 在批量操作下拉菜单中选择“停用”
4. 点击“应用”

### 2.3 测试问题[​](#23-test-the-issue "直接链接到 2.3 测试问题")

1. **清除任何缓存** - 如果您使用缓存插件，请清除所有缓存
2. **测试有问题的功能** - 现在能够正常工作吗？
3. **检查性能** - 执行时间是否提高？

**如果问题已解决：** 您存在插件冲突。继续进行第 2.4 步。

**如果问题仍然存在：** 问题可能不是插件冲突。考虑：

* 服务器资源问题（见[服务器性能](/zh-CN/support/performance/server.md)）
* 主题冲突（见第 3 步）
* WordPress/WooCommerce 核心问题

### 2.4 逐个启用插件[​](#24-enable-plugins-one-by-one "直接链接到 2.4 逐个启用插件")

现在您需要识别是哪个插件导致了冲突：

1. **启用一个插件** - 首先从最重要的插件开始
2. **测试功能** - 检查问题是否重现
3. **如果没有问题** - 启用下一个插件并再次测试
4. **如果问题重现** - 您找到了冲突的插件！

**插件优先顺序（按此顺序启用）：**

1. **安全插件** - Wordfence、Sucuri 等
2. **SEO 插件** - Yoast、RankMath 等
3. **性能插件** - 缓存、优化
4. **支付网关** - Stripe、PayPal 等
5. **其他 WooCommerce 扩展**
6. **常规 WordPress 插件**

### 2.5 记录您的发现[​](#25-document-your-findings "直接链接到 2.5 记录您的发现")

当您识别出冲突的插件时：

1. **记录插件名称和版本**
2. **记录其导致的具体问题**
3. **检查是否有可用的更新版本**
4. **寻找提供类似功能的替代插件**

## 第 3 步：检查主题冲突[​](#step-3-check-for-theme-conflicts "直接链接到 第 3 步：检查主题冲突")

虽然主题很少会影响 WCPOS（因为它使用自己的界面），但有时可能会造成以下问题：

* 结账过程（如果使用网页结账网关）
* 管理区域功能
* API 响应

### 使用默认主题进行测试[​](#test-with-a-default-theme "直接链接到 使用默认主题进行测试")

1. **在您的暂存网站上**，切换到默认的 WordPress 主题：

   <!-- -->

   * Twenty Twenty-Four
   * Twenty Twenty-Three
   * Twenty Twenty-Two

2. **测试有问题的功能**

3. **如果问题已解决** - 您的主题存在冲突

主题影响

与插件相比，主题导致 WCPOS 问题的可能性要小得多。POS 界面独立于您的主题运行。然而，主题可能会影响：

* WooCommerce 结账页面
* WordPress 后台功能
* REST API 响应

## 第 4 步：解决插件冲突[​](#step-4-resolving-plugin-conflicts "直接链接到 第 4 步：解决插件冲突")

一旦您识别出冲突的插件，您有几个选项：

### 选项 1：更新插件[​](#option-1-update-the-plugin "直接链接到 选项 1：更新插件")

1. **检查更新** - 冲突可能在新版本中得到修复
2. **先在您的暂存网站上更新插件**
3. **进行彻底测试**，再在生产网站上更新

### 选项 2：寻找替代插件[​](#option-2-find-an-alternative "直接链接到 选项 2：寻找替代插件")

1. **研究提供相同功能的替代插件**
2. **在您的暂存网站上测试替代插件**
3. **如果更换插件，请迁移设置**

### 选项 3：联系插件开发者[​](#option-3-contact-plugin-developer "直接链接到 选项 3：联系插件开发者")

1. **向插件开发者报告冲突**

2. **提供详细信息：**

   * 涉及的插件版本
   * WordPress 和 WooCommerce 版本
   * 精确的错误消息或行为
   * 重现问题的步骤

### 选项 4：定制解决方案[​](#option-4-custom-solution "直接链接到 选项 4：定制解决方案")

对于无法替代的必要插件：

1. **联系 WordPress 开发者**，创建定制修复
2. **考虑插件特定钩子**，禁用冲突功能
3. **在与 POS 相关的页面上使用条件逻辑**禁用插件

## 常见冲突插件类型[​](#common-conflicting-plugin-types "直接链接到 常见冲突插件类型")

### 高风险插件分类[​](#high-risk-plugin-categories "直接链接到 高风险插件分类")

**安全插件：**

* 可能会阻止 API 请求
* 可能干扰身份验证
* 通常具有激进的防火墙规则

**缓存插件：**

* 可能不当缓存 API 响应
* 可能干扰实时数据
* 可能导致过期数据问题

**SEO 插件：**

* 大插件可能减慢后台速度
* 可能添加不必要的数据库查询
* 可能干扰 REST API 响应

**页面构建器：**

* 通常在后台加载重脚本
* 可能与 WooCommerce 后台页面冲突
* 可能干扰结账过程

**会员/限制插件：**

* 可能阻止 API 访问
* 可能干扰用户身份验证
* 可能限制对所需资源的访问

### 低风险插件分类[​](#lower-risk-plugin-categories "直接链接到 低风险插件分类")

**联系表单：** 通常不会干扰 WCPOS **社交媒体插件：** 很少引起冲突 **分析插件：** 一般是安全的，除非非常庞大 **基本内容插件：** 通常兼容

## 已知插件冲突[​](#known-plugin-conflicts "直接链接到 已知插件冲突")

以下插件已知会干扰 WCPOS。许多问题已在近期 WCPOS 版本中自动修复——**更新到最新版本**即可解决这些问题，无需任何配置。

大多数修复都是“排除 POS”

共同的根源：WCPOS 依赖 WooCommerce REST API，并在 iframe 中渲染某些流程（登录、支付、收据）。通常的修复方法是从另一个插件中**排除 POS 端点/URL**（`/wp-json/wcpos/`、`/wp-json/wc/v3/` 和 `/pos/` 路径）——而不是完全禁用它。

### 安全与登录插件[​](#security-and-login-plugins "直接链接到 安全与登录插件")

这是**最常见**的冲突来源，尤其是对于桌面/移动应用登录。

| 插件                                      | 症状                                                                                    | 修复                                                                                                                       |
| ----------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Wordfence**                             | 防火墙阻止 REST API；2FA 代码字段无法在登录 iframe 中渲染；限制性 CSP 可能阻止 POS 资源 | 在防火墙中将 `/wp-json/wcpos/` 和 `/wp-json/wc/v3/` 加入白名单。对于 2FA：临时为 POS 用户禁用它。CSP 在 v1.9.0+ 中自动剥离 |
| **Really Simple Security**                | 阻止 API 访问 / 强制重定向                                                              | 在插件的 **Advanced** 设置中禁用任何 REST API 限制                                                                         |
| **WPS Hide Login**                        | 自定义登录 URL 破坏应用登录 iframe                                                      | 为 POS 访问使用标准的 `/wp-admin/` 登录 URL                                                                                |
| **iThemes / Solid Security**              | 阻止 REST API 或因 POS 调用触发暴力破解锁定                                             | 仅将 POS 端点和服务器自身的 IP 加入白名单——避免一刀切的 IP 规则                                                            |
| **Sucuri**                                | WAF 阻止 API 请求                                                                       | 在 Sucuri 仪表板中将 REST API 端点加入白名单                                                                               |
| **Security Optimizer**                    | 阻止管理员 POS 登录（*"use customize login URL"*）                                      | 先通过自定义 URL 登录 WP Admin，然后前往 `/pos`                                                                            |
| **Force Login**（及类似的 REST 认证插件） | `/wp-json/` 返回 401/403；旧版应用报告 *"Site does not seem to be a WordPress site"*    | 允许对 POS 端点进行未经身份验证的访问，或在初始连接期间禁用。v1.x 应用现在会显示真实的错误消息                             |
| **LoginPress**                            | 强制基于电子邮件的登录；破坏多用户 POS 登录                                             | 允许用户名登录，或为 POS 访问禁用                                                                                          |
| **JWT Authentication plugins**            | 激活后所有 POS API 请求返回 403（登录可能成功，其他全部失败）                           | 在 v1.8.x+ 中自动修复。在旧版本上，停用 JWT 插件或排除 POS 端点                                                            |
| **Captcha / reCAPTCHA**                   | 桌面应用中的登录循环（验证码无法在 iframe 中渲染）                                      | 为 POS 登录 URL 禁用验证码                                                                                                 |
| **Defender Pro**                          | `X-Frame-Options` 标头阻止所有 POS iframe（登录、支付、收据）                           | 为 `/pos/` 添加 POS 特定例外，而不是在站点范围内禁用 `X-Frame-Options`                                                     |
| **Jetpack CRM Client Portal**             | 完全破坏 POS 登录                                                                       | 仅禁用 Client Portal 扩展                                                                                                  |

### 性能、缓存与优化插件[​](#performance-caching-optimisation-plugins "直接链接到 性能、缓存与优化插件")

| 插件                                           | 症状                                                                                               | 修复                                                                   |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **WP Rocket、Autoptimize、Hummingbird、Smush** | 延迟/压缩 JS 破坏结账和 Stripe Terminal                                                            | 从 JS 优化中排除 `/pos/` URL                                           |
| **LiteSpeed Cache**                            | 桌面应用结账时持续重新加载循环；限制性 CSP                                                         | 更新 WCPOS、清除缓存、从缓存中排除 POS 页面。CSP 在 v1.9.0+ 中自动剥离 |
| **Image Prioritizer**                          | 滥用 HTTP `Link` 标头，破坏 REST API 发现；桌面应用显示 *"does not appear to be a WordPress site"* | 停用该插件                                                             |

### 页面构建器与前端注入器[​](#page-builders-front-end-injectors "直接链接到 页面构建器与前端注入器")

| 插件                             | 症状                                                                       | 修复                                          |
| -------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
| **Elementor**                    | `elementor-frontend.js` 破坏 POS iframe 内的结账折叠面板——支付方式无法展开 | 从 Elementor 脚本加载中排除 POS 页面          |
| **Omnisend / 营销插件**          | 向结账 iframe 注入脚本，破坏布局和支付                                     | 使用 POS **Checkout Settings** 禁用非必要脚本 |
| **MyStickyElements / Complianz** | 向结账 iframe 注入覆盖层（吸附按钮、Cookie 横幅）                          | 配置它们以排除 `/pos/` URL                    |

### WooCommerce 扩展与其他插件[​](#woocommerce-extensions-other-plugins "直接链接到 WooCommerce 扩展与其他插件")

| 插件                                                      | 症状                                                                  | 修复                                                                   |
| --------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **WooCommerce Subscriptions**                             | v1.7→v1.8 升级期间的迁移脚本冲突                                      | 停用 Subscriptions、激活 POS Pro（让迁移运行），然后重新启用           |
| **WP Activity Log**                                       | 记录每个 POS 操作 → postmeta 膨胀 → *"only 10 products"*              | 禁用它，或从日志记录中排除 POS 文章类型                                |
| **Jetpack / Astra / Xero**（任何挂钩 `save_post` 的插件） | 每次 POS API 调用都产生重复的元数据行（某店铺一个产品达到 36,867 行） | 在 v1.8.12+（免费版）/ v1.8.14+（Pro）中通过清理迁移自动修复——只需更新 |
| **Stripe Tax**                                            | 与通过 REST API 创建的订单不兼容（POS 即以此方式创建订单）            | 无变通方案——不兼容                                                     |
| **Mollie**                                                | 可能从 POS 结账中隐藏 BACS（银行转账）方式                            | 将 Mollie 更新到最新版本                                               |
| **CTX Feed**                                              | POS 设置页面上间歇性的 403 错误                                       | 停用以确认；无已知变通方案                                             |
| **第三方条码扫描枪插件**                                  | 破坏订单 API JSON，导致订单创建/显示失败                              | 禁用它们；使用 POS 内置的条码扫描                                      |
| **MailerLite**（Signup Forms + WooCommerce）              | POS 订单创建时出现 500 错误（内存耗尽）                               | 停用以确认，然后联系 MailerLite                                        |
| **The Courier Guy Shipping**                              | POS 订单创建因服务器错误而失败                                        | 回滚到先前版本，或联系开发者                                           |
| **PixelYourSite / PixelMySite**                           | 致命错误：*call to member function `is_type()` on bool*               | 临时禁用                                                               |
| **Google Listings & Ads**                                 | 自动加载器冲突 → *"Class WCPOS\…\Stores not found"* 严重错误          | 删除所有 POS 插件，仅重新安装最新的 Pro 独立版                         |

Stripe Terminal：不要全局启用它

**Stripe Terminal** 网关应该**仅**在 POS 设置内启用，绝不在 `WooCommerce > Settings > Payments` 中启用。全局启用它会使其出现在您的公开商店结账页面上，并使在线结账流程崩溃。

### 服务器级冲突[​](#server-level-conflicts "直接链接到 服务器级冲突")

| 来源                                                 | 症状                                         | 修复                                                                                                                             |
| ---------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **自定义 CSP 标头**（`.htaccess`、Nginx 或安全插件） | POS 卡在 Logo 上；JS/CSS 被阻止              | 在 v1.9.0+ 中于 POS 页面上自动剥离。对于服务器级 CSP，在 `script-src`/`style-src` 中允许 `cdn.jsdelivr.net`，或添加 `/pos/` 例外 |
| **GoDaddy Website Firewall**                         | 阻止 `/wp-json/`（*"Received 'undefined'"*） | 在防火墙中允许 `/wp-json/` URL 路径——见[服务器性能](/zh-CN/support/performance/server.md#hosting-specific-notes)                 |

## 预防技巧[​](#prevention-tips "直接链接到 预防技巧")

### 定期维护[​](#regular-maintenance "直接链接到 定期维护")

1. **保持插件更新** - 始终使用最新版本
2. **移除未使用的插件** - 不仅停用，还删除它们
3. **在暂存上测试更新**，再应用于生产网站
4. **定期监控性能**，使用[服务器性能](/zh-CN/support/performance/server.md)指标

### 插件选择最佳实践[​](#plugin-selection-best-practices "直接链接到 插件选择最佳实践")

1. **选择声誉良好的开发者** - 检查评论和更新频率
2. **避免冗余功能** - 不要安装多个执行相同操作的插件
3. **阅读兼容性信息** - 检查插件是否经过 WooCommerce 测试
4. **从少数插件开始** - 根据需要逐步添加功能

## 寻求帮助[​](#getting-help "直接链接到 寻求帮助")

如果您无法解决插件冲突：

### 对于 Pro 用户[​](#for-pro-users "直接链接到 对于 Pro 用户")

Pro 支持

Pro 用户在插件冲突解决方面获得优先支持。我们的团队可以帮助您识别和解决冲突。

### 社区支持[​](#community-support "直接链接到 社区支持")

[Discord Community](https://wcpos.com/discord)<support@wcpos.com>

### 联系支持时[​](#when-contacting-support "直接链接到 联系支持时")

请提供：

1. **活动插件列表**及版本
2. **WordPress 和 WooCommerce 版本**
3. **问题的详细描述**
4. **您已经尝试过的步骤**
5. **日志中的错误消息**
6. **相关的服务器性能指标**

## 相关文档[​](#related-documentation "直接链接到 相关文档")

[致命错误如何找到致命错误日志](/zh-CN/support/troubleshooting/critical-error.md)

[日志理解 WCPOS 日志和指标](/zh-CN/support/logs.md)

[服务器性能诊断性能问题](/zh-CN/support/performance/server.md)

[结账性能优化结账速度](/zh-CN/support/performance/checkout.md)