NopCommerce 3.30 中自建 payment plugin 未显示

2026-10-24支付小周

结论

自建支付插件完成编码后，并不会自动出现在“Payment Methods”页面。插件需要先正确输出到 Nop.Web\Plugins 目录并被 nopCommerce 识别，然后在后台重新加载本地插件列表并完成安装。

如果没有显示，通常是以下原因：

插件 DLL 没有输出到 Presentation\Nop.Web\Plugins\<插件目录>。
Description.txt 缺失、内容有误，或者 SupportedVersions 不包含 3.30。
插件还没有在后台安装。
修改插件后，没有重新加载插件列表或重启应用程序。
插件程序集加载失败，例如缺少依赖或编译目标不兼容。

正确的处理顺序

重新生成解决方案后，先确认插件目录结构类似于：

Presentation
└── Nop.Web
    └── Plugins
        └── Payments.MyPayment
            ├── Description.txt
            ├── Nop.Plugin.Payments.MyPayment.dll
            └── 其他依赖 DLL

然后进入后台：

Configuration -> Plugins -> Local Plugins

点击重新加载插件列表，找到自建插件并执行安装。安装成功后，再进入：

Configuration -> Payment -> Payment Methods

这时支付方式才会出现在列表中。

不同的 3.30 安装包或后台语言可能使用不同的菜单文字，例如“Plugins”“Local Plugins”或“Reload list of plugins”，但操作流程一致。

检查 `Description.txt`

nopCommerce 3.30 通过插件目录中的 Description.txt 读取插件元数据。基本配置可以参考：

Group: Payment methods
FriendlyName: My payment method
SystemName: Payments.MyPayment
Version: 1.00
SupportedVersions: 3.30
Author: Your name
DisplayOrder: 1
FileName: Nop.Plugin.Payments.MyPayment.dll

检查时注意以下几点：

FileName 必须与实际生成的 DLL 文件名完全一致。
SupportedVersions 必须包含 3.30。
SystemName 应当保持唯一，通常采用 Payments.XXX 格式。
文件名必须是 Description.txt，并放在插件目录根层。
不能只把 Description.txt 留在插件源码目录中，它还需要复制到 Nop.Web\Plugins。

如果 SupportedVersions 填写的是其他版本，例如：

SupportedVersions: 3.40

nopCommerce 3.30 不会将其识别为当前版本可用的插件。

检查项目输出目录

插件项目的生成结果需要直接或间接复制到 Web 项目的插件目录。以常见的解决方案目录结构为例，可以把项目输出路径设置为：

..\..\Presentation\Nop.Web\Plugins\Payments.MyPayment\

实际使用的相对路径取决于插件项目的位置，不应直接照搬。判断是否正确，只需确认生成完成后，插件 DLL 和 Description.txt 是否确实存在于当前运行实例的 Nop.Web\Plugins\Payments.MyPayment 目录中。

Description.txt 的属性还应设置为：

Build Action: Content
Copy to Output Directory: Copy if newer

如果通过项目文件配置，可以使用类似写法：

<ItemGroup>
  <Content Include="Description.txt">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </Content>
</ItemGroup>

具体的项目文件格式取决于所用的 Visual Studio 和项目类型。无论采用哪种配置，目的都是让描述文件随插件一起输出。

检查支付插件实现

插件类必须实现 nopCommerce 3.30 要求的支付接口，通常还需要继承 BasePlugin：

using Nop.Core.Plugins;
using Nop.Services.Payments;

namespace Nop.Plugin.Payments.MyPayment
{
    public class MyPaymentProcessor : BasePlugin, IPaymentMethod
    {
        // 实现 nopCommerce 3.30 中 IPaymentMethod 要求的全部成员
    }
}

具体实现应以项目实际引用的 nopCommerce 3.30 IPaymentMethod 接口定义为准。不要直接复制其他版本的完整实现，因为不同版本的接口成员、返回类型和方法签名可能不同。

成功编译不等于运行时能够正常加载。如果类没有完整实现 IPaymentMethod，引用了不兼容版本的程序集，或者缺少依赖 DLL，插件发现过程仍然可能失败。

重新加载后仍然找不到插件

可以按以下顺序排查：

确认当前启动的是预期的 Nop.Web 实例，而不是另一份发布目录中的站点。
删除插件目录中的旧 DLL，再重新生成，避免程序加载过期程序集。
检查 Description.txt 中的 FileName、SystemName 和 SupportedVersions。
确认插件引用的是当前站点所用的 nopCommerce 3.30 程序集。
检查插件依赖的第三方 DLL 是否已复制到插件目录或应用程序能够解析的位置。
重启站点或应用程序池，再重新加载本地插件列表。
查看 App_Data 下的日志或后台系统日志，查找程序集加载异常、类型加载异常和依赖缺失信息。

常见错误包括：

Could not load file or assembly ...

Could not load type ...

ReflectionTypeLoadException

出现这些错误时，问题不在支付方式页面，而是插件程序集尚未成功加载。

不建议直接修改已安装插件列表

nopCommerce 3.30 会保存已安装插件的信息，但不建议手工编辑相关文件来“强制安装”。插件应当在以下页面中安装：

Configuration -> Plugins -> Local Plugins

后台安装过程可能会调用插件的 Install() 方法、创建设置或执行其他初始化逻辑。直接修改文件会绕过这些步骤。

需要先确认插件已经出现在本地插件列表中，并且安装成功。完成这一步后，它才会作为支付方式出现在 Payment Methods 页面。