Smartstore模块开发实战：从Hello World模块到打包发布上架完整教程-平芜编程栈

Smartstore模块开发实战：从Hello World模块到打包发布上架完整教程

【免费下载链接】SmartstoreA modular, scalable and ultra-fast open-source all-in-one eCommerce platform built on ASP.NET Core 10项目地址: https://gitcode.com/GitHub_Trending/smar/Smartstore

本文带你完成Smartstore 模块开发的完整闭环：理解模块体系、搭建 Hello World 模块、编写配置页与多语言资源，最后用 Smartstore Packager 打包发布并上架到店铺插件中心。Smartstore 是一款基于 ASP.NET Core 构建的开源一体化电子商务平台，模块化是它最核心的扩展能力——无论是支付、物流、税务还是界面组件，都可以通过一个模块轻松接入。

一、为什么选择 Smartstore 做模块开发

Smartstore 的架构天然为"插件化"而生：核心只负责商品、订单、客户、内容等基础能力，而一切增值功能都交给**模块（Module）**来实现。一个模块可以：

🧩替换或扩展服务：接入 PayPal、Stripe 等支付，或自定义运费、税率计算
🖥️修改 UI：向页面注入小组件、管理后台菜单、标签助手
⚙️改变工作流：监听订单事件、自定义审批流、对接外部 API

模块本质上是一个普通的 C# 类库项目，最终编译成一个程序集，被 Smartstore 动态加载到应用域中。官方模块（如支付、物流、谷歌分析）就存放在 src/Smartstore.Modules/ 目录下，是最好的参考样板。

💡 提示：模块可以使用 Smartstore API，也可以完全不依赖它。只要满足两个硬性要求，就是一个合法的模块——module.json清单文件 + 实现IModule接口的Module.cs入口类。

二、模块的最小结构：module.json 与 Module.cs

1. module.json：模块的"身份证"

module.json描述模块的元数据，是插件管理器（Plugin Manager）识别和展示模块的依据。其字段规范定义在 module.schema.json 中，必填项只有 3 个：

字段	说明
`SystemName`	模块系统名，通常即程序集名（不含扩展名），如`MyOrg.HelloWorld`
`FriendlyName`	英文友好名称，用户在后台看到的名字
`Version`	当前模块版本，如`5.0`

可选字段还有Author（作者）、Group（分组，如 Payment / CMS / SEO）、MinAppVersion（最低兼容的 Smartstore 版本）、ResourceRootKey（多语言资源根键）等。注意：模块版本号应与当前 Smartstore 版本保持一致，版本不兼容的模块不会被加载。

2. Module.cs：安装与卸载的入口类

每个模块都需要一个入口类，约定俗成命名为Module.cs（内部类，放在项目根目录）。推荐继承抽象基类 ModuleBase，它已实现公共逻辑，你只需覆写两个方法：

InstallAsync()：模块安装时调用——保存默认设置、导入多语言资源，并务必调用base.InstallAsync(context)
UninstallAsync()：卸载时调用——清理设置与语言资源（官方建议不要删除自定义业务数据，方便日后重装）

三、实战：搭建 Hello World 模块

以下流程参照官方教程 building-a-simple-hello-world-module.md 编写，只需 5 步即可跑通第一个模块。

第 1 步：创建项目

打开解决方案Smartstore.sln
在Modules文件夹上右键 → 新建类库项目，命名为MyOrg.HelloWorld，物理路径必须是src/Smartstore.Modules/
修改.csproj，将编译输出指向 Web 模块目录：

<PropertyGroup> <Product>A Hello World module for Smartstore</Product> <OutputPath>..\..\Smartstore.Web\Modules\MyOrg.HelloWorld</OutputPath> <OutDir>$(OutputPath)</OutDir> </PropertyGroup>

每次构建，模块都会被自动复制到Smartstore.Web/Modules/，应用从这里动态加载模块程序集。

⚠️ 易错点：src/Smartstore.Modules/是源码目录，src/Smartstore.Web/Modules/是构建输出目录，两者不要混淆。

第 2 步：添加 module.json

按上文说明填写清单，设置SystemName为MyOrg.HelloWorld、Group为Admin、ResourceRootKey为Plugins.MyOrg.HelloWorld，并把该文件的构建设置为Content / Copy if newer。

第 3 步：编写入口类与设置类

入口类Module : ModuleBase, IConfigurable——实现IConfigurable接口后，插件管理器中会出现Configure按钮
新建Configuration/HelloWorldSettings.cs设置类（实现ISettings），例如一个Name字符串属性，默认值"John Smith"

安装模块时，TrySaveSettingsAsync<HelloWorldSettings>()会把默认值写入数据库；卸载时自动清理。

第 4 步：管理后台配置页（MVC 三件套）

Smartstore 遵循 MVC 模式，配置页只需三样东西：

组件	文件	作用
控制器	`Controllers/HelloWorldAdminController.cs`	继承`AdminController`，GET/POST 两个`Configure`动作分别用`[LoadSetting]`与`[SaveSetting]`特性自动加载/保存设置
视图模型	`Models/ConfigurationModel.cs`	用`[LocalizedDisplay]`特性绑定多语言显示名
视图	`Views/HelloWorldAdmin/Configure.cshtml`	复用`_ConfigureModule`布局，用`setting-editor`标签助手渲染输入框

第 5 步：前台页面与多语言

再添加一个前台控制器HelloWorldController（继承PublicController）和视图Views/HelloWorld/PublicInfo.cshtml，访问helloworld/publicinfo路由即可看到 "Hello John Smith" 的问候页。

多语言资源放在Localization/目录的resources.en-us.xml等 XML 文件中（en-us替换为对应语言代码），安装模块时自动导入。视图模型属性通过[LocalizedDisplay("*Name")]引用这些资源，详见 localizing-modules.md。

✅跑通验证：编译后进入后台 → 插件 → 管理插件 → Hello World → 安装，点击Configure修改名字，前台刷新看到变化——你的第一个模块开发完成了！

四、打包发布：Smartstore Packager 一键出包

模块开发完成后，要分发给其他店铺，就进入打包发布环节。

1. Release 模式构建

发布前必须切换到Release配置构建模块（在模块项目上右键 Build 即可），产物会输出到.csproj中定义的OutputPath。版本编号约定：热修复递增修订号，例如5.0.1→5.0.1.1→5.0.1.2。

2. 用 Packager 生成安装包

Smartstore 官方提供Smartstore Packager（源码位于 tools/Smartstore.Packager/，打包引擎见 PackagerEngine.cs），工作流很简单：

打开仓库根目录的Smartstore.Tools.sln，构建Smartstore.Packager项目
启动后选择构建产物目录，点击ReadExtensions列出所有模块
选中目标模块 → 指定输出目录 → 点击Create Package

生成的包按Smartstore.Module.{模块系统名}.{版本号}.zip命名，例如Smartstore.Module.MyOrg.HelloWorld.5.0.zip。

3. 命令行方式：适合 CI 自动化

对于持续集成场景，仓库内置了无界面版 Smartstore.Packager.Cli，与 GUI 版共享同一套打包逻辑，产物完全一致：

Smartstore.Packager.Cli pack --root <构建产物目录> --output <输出目录> --extension MyOrg.HelloWorld

支持--all批量打包所有模块与主题，成功时退出码为0，完整参数说明见 deploying-modules.md。

五、上架：让模块进入其他店铺

打包好的 zip 就是模块的"上架包"，交付方式有两种：

方式	适用场景	说明
📦上传安装包（推荐）	分发给第三方店主	店主在后台插件管理器直接上传 zip，Smartstore 自动重启应用完成安装，无需停掉应用池
🌐FTP / RDP 上传	自有服务器运维	将模块文件上传到服务器`Modules`目录后重启应用，再在插件管理器中安装

上架小贴士📝

module.json的Group决定模块在后台列表中的分类展示，选对分组（Payment / CMS / SEO…）能让店主更容易发现你的模块
卸载时保留业务数据、MinAppVersion如实声明，是模块专业度的基本体现
私有依赖的 NuGet 包务必登记到PrivateReferences，否则运行时抛错

六、延伸阅读：官方文档导航

主题	文档位置
模块入门（结构、清单、最佳实践）	dev-docs/compose/modules/getting-started-with-modules.md
Hello World 完整教程	dev-docs/compose/modules/tutorials/building-a-simple-hello-world-module.md
部署与打包发布	dev-docs/compose/modules/deploying-modules.md
控制器与 ViewComponent	dev-docs/compose/modules/controllers-and-viewcomponents.md
模块多语言	dev-docs/compose/modules/localizing-modules.md
可授权商业模块	dev-docs/compose/modules/licensable-modules.md
module.json 字段规范	src/Smartstore.Modules/module.schema.json