PrestaShop 1.7 结账页面无可用支付方式

2026-10-24支付老李

结论

这通常不是支付模块互不兼容，而是 PrestaShop 按当前订单条件筛选支付方式后，没有模块能同时满足所有限制。建议重点检查：

carrier 与支付模块的关联；
carrier 的 reference 是否因删除、重建或反复修改而发生变化；
国家、货币、客户组和店铺限制；
支付模块是否正确实现并返回 PaymentOption；
缓存或第三方结账模块是否仍在读取旧配置。

后台无法勾选 carrier 限制也不正常。排除员工权限和页面脚本问题后，常见原因是 module_carrier 中缺少关联记录、存在残留记录，或记录仍指向旧的 carrier reference。

为什么只有一个 carrier 能显示支付方式

PrestaShop 1.7 不会只根据 carrier 决定是否显示支付方式。进入付款步骤后，系统会结合当前购物车的多个条件筛选支付模块，包括：

配送国家；
使用的货币；
客户所属的客户组；
当前店铺；
所选 carrier；
支付模块自身的可用性判断；
模块在 paymentOptions Hook 中实际返回的内容。

因此，即使支付模块已经启用，只要有一项限制不匹配，它就不会出现在结账页。

carrier 有两个容易混淆的标识：

id_carrier：当前 carrier 记录的 ID；
id_reference：同一个逻辑 carrier 在不同版本记录之间共用的引用 ID。

PrestaShop 通常使用 id_reference 保存支付方式与 carrier 的关联。修改 carrier 时，系统可能生成新的 id_carrier，同时保留原来的 id_reference。如果 carrier 被删除后重新创建，则可能获得新的 reference，原有关联也会随之失效。

建议的排查顺序

1. 检查所有支付限制

进入后台的支付偏好或支付方式限制页面，逐项核对：

Currency restrictions
Country restrictions
Group restrictions
Carrier restrictions

确认当前订单使用的货币、配送国家、客户组和 carrier 均在允许范围内。

如果启用了多店铺，请先切换到出现问题的具体店铺上下文，再保存设置。不要只在 “All shops” 上下文中检查，因为限制记录通常包含 id_shop。

2. 检查 carrier 的适用范围

分别打开三个 carrier，确认它们适用于：

当前配送区域和国家；
当前客户组；
当前商品的重量或价格区间；
当前店铺；
当前仓库或库存配置，如果启用了相关功能。

carrier 能出现在配送步骤，并不代表后续支付模块一定允许使用它。

3. 排除后台页面问题

如果 carrier 限制页面中的复选框无法点击，可以按以下顺序检查：

使用 SuperAdmin 账号登录；
暂时关闭后台 JavaScript 合并、压缩和缓存；
清除 PrestaShop 缓存；
打开浏览器开发者工具，检查 Console 和 Network 中是否出现 JavaScript 或 Ajax 错误；
暂时切回默认后台主题；
检查是否安装了会覆盖支付偏好页面的第三方模块或 override。

同时确认页面显示的 carrier 不是已删除或停用的历史记录。

4. 清除缓存

可以在后台通过以下路径清理缓存：

Advanced Parameters > Performance > Clear cache

如果有服务器访问权限，也可以删除当前环境所对应缓存目录中的内容。目录名称会因运行环境和 PrestaShop 1.7 的具体版本而异，常见位置包括：

var/cache/prod/
var/cache/dev/

不要删除 var/cache 目录本身，也不要在未确认运行环境和备份情况时执行递归删除命令。

5. 重新安装或重置支付模块

请先在测试环境中操作：

记录支付模块的全部配置；
将模块升级到兼容当前 PrestaShop 版本的版本；
使用模块提供的 Reset 功能重新注册 Hook；
重新保存国家、货币、客户组和 carrier 限制；
创建新购物车并重新测试。

重新安装支付模块可能会删除 API 密钥、Webhook、订单状态映射等配置，因此不要直接在生产环境中盲目操作。

检查数据库关联

操作数据库前应进行完整备份，并优先在测试副本中查询。以下示例假设数据库表前缀为 ps_。如果实际前缀不同，请相应替换。

先查看当前有效的 carrier 及其 reference：

SELECT
    id_carrier,
    id_reference,
    name,
    active,
    deleted
FROM ps_carrier
ORDER BY id_reference, id_carrier;

再查看支付模块与 carrier 的关联：

SELECT
    m.id_module,
    m.name AS module_name,
    mc.id_shop,
    mc.id_reference
FROM ps_module_carrier AS mc
INNER JOIN ps_module AS m
    ON m.id_module = mc.id_module
ORDER BY m.name, mc.id_shop, mc.id_reference;

检查关联是否指向不存在的 carrier reference：

SELECT
    mc.id_module,
    m.name AS module_name,
    mc.id_shop,
    mc.id_reference
FROM ps_module_carrier AS mc
INNER JOIN ps_module AS m
    ON m.id_module = mc.id_module
LEFT JOIN ps_carrier AS c
    ON c.id_reference = mc.id_reference
WHERE c.id_reference IS NULL;

也可以单独检查某个支付模块的关联。将 payment_module_name 替换为模块的实际技术名称，例如模块目录名：

SELECT
    m.name AS module_name,
    mc.id_shop,
    mc.id_reference,
    c.id_carrier,
    c.name AS carrier_name,
    c.active,
    c.deleted
FROM ps_module AS m
LEFT JOIN ps_module_carrier AS mc
    ON mc.id_module = m.id_module
LEFT JOIN ps_carrier AS c
    ON c.id_reference = mc.id_reference
WHERE m.name = 'payment_module_name'
ORDER BY mc.id_shop, mc.id_reference, c.id_carrier;

如果查询结果中同一个 id_reference 对应多条 ps_carrier 记录，不一定表示数据有误。PrestaShop 修改 carrier 后保留历史记录很常见，应重点检查当前记录的 active 和 deleted 状态。

不建议直接向 ps_module_carrier 手工插入记录。后台保存限制时，可能还会处理店铺上下文、缓存和模块自身配置。直接修改数据库容易引入新的不一致。更稳妥的处理方式是先修复后台页面，再通过后台重新保存关联。

检查支付模块返回的 PaymentOption

如果数据库限制没有问题，但结账页仍不显示支付方式，需要检查模块是否挂载到正确的 Hook：

paymentOptions
paymentReturn

在 PrestaShop 1.7 中，支付模块通常需要通过 hookPaymentOptions() 返回 PaymentOption 数组。简化示例如下：

use PrestaShop\PrestaShop\Core\Payment\PaymentOption;

public function hookPaymentOptions($params)
{
    if (!$this->active) {
        return [];
    }

    $option = new PaymentOption();
    $option
        ->setCallToActionText($this->l('Pay now'))
        ->setAction($this->context->link->getModuleLink(
            $this->name,
            'validation',
            [],
            true
        ));

    return [$option];
}

如果模块在该方法中根据 carrier、国家、货币、订单金额或自定义条件返回空数组，即使后台限制全部正确，前台也不会显示该支付方式。对于第三方模块，尤其要检查类似下面的代码：

if (!$this->isAvailableForCarrier($params['cart']->id_carrier)) {
    return [];
}

如果这里误将 id_carrier 与 id_reference 进行比较，就可能导致只有某一个 carrier 可用。

临时定位第三方冲突

可以在测试环境中进行以下交叉测试：

切换到 Classic 默认主题；
禁用 one-page checkout 或自定义结账模块；
只保留一个官方或已确认兼容的支付模块；
逐个启用 carrier；
创建全新的客户、地址和购物车进行测试；
检查 PrestaShop 日志、PHP 日志和浏览器 Ajax 响应。

如果默认主题和原生结账流程运行正常，问题更可能出在主题、结账模块或 override。假如所有支付模块都对同一批 carrier 失效，应优先检查 carrier reference、店铺上下文和数据库限制，不必逐个排查支付模块。

注意事项

测试时应创建新购物车，因为旧购物车可能保留旧的 id_carrier。
不要只根据 carrier 的显示名称判断关联。名称相同并不代表 id_reference 相同。
多店铺环境必须核对 id_shop。
删除并重新创建 carrier 可能改变 reference，再次破坏支付关联。
修改数据库、重置模块或删除缓存前必须备份。
如果问题出现在升级后，还要核对主题、支付模块和 override 是否明确支持当前 PrestaShop 1.7 的具体小版本。

定位时，先比较正常 carrier 与异常 carrier 的 id_carrier、id_reference 和 ps_module_carrier 记录。如果异常 carrier 的 reference 没有对应的支付模块关联，通常可以确定问题来自限制配置或历史 carrier 数据。