简介：萤火商城 v2.0.8 多端版是一套轻量级、高性能、前后端分离的开源电商系统，面向希望快速搭建独立商城的开发者、创业者及二次开发学习者。系统支持微信小程序、H5、公众号与 APP 多端覆盖，前后端源码 100% 开源，所见即所得，便于按需定制个性化商城。技术栈采用 PHP7.4 + ThinkPHP6.0 + Uni-APP + Ant Design Vue，兼顾可学习性与商用稳定性。资源包共约 2000 个文件，压缩后 17.34MB，以 1175 个 PHP 后端逻辑文件、155 个 JS 脚本、46 个 CSS 样式、32 个 HTML 页面及 48 个 JSON 配置为主，另含 SQL 建表脚本、Markdown 说明文档与字体图片等静态资源，目录结构完整清晰。目前已有 267 人学习下载。读者可获得完整的前后端源码、数据库脚本与配置说明，用于本地部署、功能拆解与二次开发练习，快速理解多端电商系统的架构设计与业务实现。
1. 萤火商城 v2.0.8 多端版到底解决了什么：从一套代码到五个终端的商业闭环
如果你正在找一个能同时跑微信小程序、H5、App、PC 和抖音小程序的商城系统，萤火商城 v2.0.8 多端版大概率已经在你的候选清单里。它的核心卖点不是功能多，而是一套后端 + 一套前端代码，编译到多个终端。这意味着你不需要为每个平台单独维护一套商品、订单、用户逻辑，运营成本直接砍掉一大半。
我最早接触这个方向是因为一个做社区团购的客户，他们原本用三套独立系统分别跑小程序、H5 和 App，结果每次改价格都要同步三个后台，库存还经常对不上。萤火商城 v2.0.8 的多端方案把这个问题从根上解决了——后端只写一次 API，前端用条件编译处理平台差异。适合谁？中小型电商团队、私域运营者、需要快速验证商业模式的创业者。不适合谁？日均订单过万、需要深度定制供应链逻辑的大型平台，因为它的架构更偏向“够用且快”，而不是“大而全”。
2. 多端编译的底层逻辑：条件编译怎么让一套代码跑五个平台
2.1 条件编译不是玄学，是预处理指令的工程化
萤火商城 v2.0.8 多端版的前端基于 uni-app 框架，核心机制是条件编译。简单说，你在代码里写#ifdef MP-WEIXIN，编译器在打包微信小程序时只保留这段代码，打包 H5 时直接删掉。这不是运行时判断，是编译时裁剪，所以不会增加包体积。
我见过不少团队用运行时if (platform === 'wx')来判断，结果 H5 包里塞了一堆小程序 API 的兼容代码，首屏加载直接多出 200KB。萤火商城 v2.0.8 的做法更干净：平台差异代码在编译阶段就消失了。
具体到目录结构，pages下每个页面都可以有.vue主文件，然后通过platforms目录放平台专属覆盖文件。比如微信小程序的支付逻辑放在platforms/mp-weixin/pay.js，H5 的放在platforms/h5/pay.js，编译时自动替换。
2.2 后端 API 的统一设计：为什么订单接口要返回五种终端的字段
多端版的后端不是简单地把所有字段都返回给所有终端。萤火商城 v2.0.8 在 API 层做了终端标识透传。每个请求头里带X-Client-Platform，后端根据这个字段决定返回哪些字段。
举个例子，商品详情接口在微信小程序里需要返回wx_mini_path（用于分享卡片），在 H5 里需要返回h5_share_url，在 App 里需要返回app_deeplink。如果全部返回，H5 的 JSON 体积会多出 30%。萤火商城 v2.0.8 的做法是：基础字段全返回，平台专属字段按需返回。
// 后端 API 中间件示例：根据终端裁剪响应字段 const platformFields = { 'mp-weixin': ['wx_mini_path', 'wx_share_title'], 'h5': ['h5_share_url', 'h5_pay_type'], 'app': ['app_deeplink', 'app_pay_type'], 'mp-toutiao': ['tt_microapp_path'], 'pc': ['pc_qr_code'] }; function filterResponse(data, platform) { const allowed = platformFields[platform] || []; const baseFields = ['id', 'name', 'price', 'stock', 'cover']; // 只保留基础字段 + 当前平台专属字段 return Object.keys(data) .filter(key => baseFields.includes(key) || allowed.includes(key)) .reduce((obj, key) => ({ ...obj, [key]: data[key] }), {}); }这段代码的关键在于baseFields和allowed的分离。基础字段是所有终端都需要的，平台专属字段按X-Client-Platform动态追加。参数怎么改？如果你新增了一个终端（比如快手小程序），只需要在platformFields里加一个 key，然后在请求头里传对应的值即可，不需要改任何业务逻辑。
提示：
X-Client-Platform的值必须和前端编译时的process.env.UNI_PLATFORM保持一致，否则会出现字段裁剪错误。
2.3 本地跑通多端编译的最小命令集
假设你已经拿到了萤火商城 v2.0.8 的源码包，目录结构通常是backend（后端）和frontend（前端）。后端我一般用 PHP 7.4 + MySQL 5.7，前端用 Node 14 + HBuilderX 或 CLI。
# 1. 后端初始化：导入数据库并配置连接 cd backend cp .env.example .env # 编辑 .env，设置 DB_DATABASE=fire_shop、DB_USERNAME=root、DB_PASSWORD=你的密码 php think migrate:run # 执行数据库迁移 php think seed:run # 导入基础数据（商品分类、默认配置） # 2. 前端安装依赖 cd ../frontend npm install --registry=https://registry.npmmirror.com # 3. 编译微信小程序（开发模式，带热更新） npm run dev:mp-weixin # 编译产物在 dist/dev/mp-weixin，用微信开发者工具打开这个目录 # 4. 编译 H5（开发模式） npm run dev:h5 # 默认跑在 localhost:8080 # 5. 编译 App（需要 HBuilderX 或自定义基座） npm run dev:app-plus这里有几个参数容易翻车。npm run dev:mp-weixin生成的dist/dev/mp-weixin目录不能直接双击打开，必须用微信开发者工具“导入项目”，否则会报app.json找不到。H5 编译时如果后端 API 地址没配好，跨域问题会让你在浏览器控制台看到一堆 CORS 报错，解决办法是在vue.config.js里配devServer.proxy。
// vue.config.js 代理配置示例 module.exports = { devServer: { proxy: { '/api': { target: 'http://localhost:8000', // 后端地址 changeOrigin: true, pathRewrite: { '^/api': '/api' } } } } };changeOrigin: true是为了让后端收到的 Host 头是localhost:8000而不是localhost:8080，很多后端框架的路由匹配依赖这个。pathRewrite在这里其实没改路径，但如果你后端 API 前缀不是/api，就需要在这里重写。
3. 商业授权版和普通版的真实差异：哪些功能值得你掏钱
3.1 授权校验的代码位置与绕过风险
萤火商城 v2.0.8 商业版和普通版最大的区别在backend/app/common/library/Auth.php这个文件。商业版会在这里校验域名授权，普通版直接返回true。我见过有人把商业版的Auth.php替换成普通版的来“免费使用”，结果三个月后系统突然无法下单——因为商业版还有一处隐藏校验在订单创建前的中间件里。
// 商业版授权校验的核心逻辑（简化示意） public function check() { $domain = request()->domain(); $license = cache('fire_shop_license'); if (!$license) { $license = $this->fetchLicenseFromServer($domain); cache('fire_shop_license', $license, 86400); } // 校验域名、有效期、版本号 if ($license['domain'] !== $domain || $license['expire_time'] < time()) { throw new Exception('授权无效'); } return true; }这段代码的关键参数是expire_time和domain。商业授权版通常按域名绑定，一个授权只能用于一个顶级域名。如果你在本地开发，request()->domain()返回的是localhost，这时候需要手动在后台配置“开发模式白名单”，否则本地都跑不起来。
注意：不要试图修改
expire_time的校验逻辑，商业版在订单、支付、退款三个核心链路都有独立的授权检查，改一处没用。
3.2 多端版独有的营销模块：拼团、秒杀、分销的终端适配
普通版只有基础的商品和订单，商业版多端版额外带了拼团、秒杀、分销三个营销模块。这三个模块在多端环境下的适配成本很高，也是商业版最值钱的部分。
以拼团为例，微信小程序里可以用wx.shareAppMessage直接分享拼团链接，H5 里只能用navigator.share（兼容性差）或者复制链接，App 里可以用原生分享面板。萤火商城 v2.0.8 在frontend/utils/share.js里做了统一封装：
// 统一分享接口，根据平台调用不同 API export function shareGroupBuy(groupId, title) { const platform = process.env.UNI_PLATFORM; const link = `/pages/group/detail?id=${groupId}`; // #ifdef MP-WEIXIN wx.shareAppMessage({ title, path: link }); // #endif // #ifdef H5 if (navigator.share) { navigator.share({ title, url: window.location.origin + link }); } else { // 降级方案：复制链接 copyToClipboard(window.location.origin + link); uni.showToast({ title: '链接已复制', icon: 'none' }); } // #endif // #ifdef APP-PLUS uni.share({ provider: 'weixin', scene: 'WXSceneSession', href: link, title }); // #endif }这段代码的工程价值在于：业务层只需要调用shareGroupBuy，不需要关心当前是什么平台。参数groupId和title是业务数据，link是统一路由。如果你要新增一个平台（比如抖音小程序），只需要加一个#ifdef MP-TOUTIAO分支，业务代码零改动。
3.3 授权版的价格锚点与投入回报测算
商业授权版的价格通常在几千元级别（具体以官方渠道为准），对于个人开发者来说不算便宜。但如果你算一笔账：自己从零实现多端编译 + 拼团 + 秒杀 + 分销，至少需要 2 个前端 + 1 个后端干 3 个月，人力成本远超授权费。而且萤火商城 v2.0.8 的代码结构比较清晰，二次开发的门槛不高。
我一般建议客户先买普通版跑通业务流程，确认这个系统能支撑你的商业模式后，再升级商业版。因为普通版和商业版的数据表结构完全一致，升级时只需要替换代码文件，不需要迁移数据。
4. 二次开发避坑：从数据库表名到前端路由的五个血泪教训
4.1 坑一：修改商品表字段后，多端编译报错但原因不在前端
现象：你在goods表加了一个custom_tag字段，后端 API 也返回了，但微信小程序编译时报undefined is not a function。
原因：萤火商城 v2.0.8 的前端在store/modules/goods.js里对商品对象做了Object.freeze，新增字段如果没有在defaultGoods模板里声明，会被冻结导致后续赋值失败。
解决：在store/modules/goods.js的defaultGoods对象里加上custom_tag: ''，然后再在 API 返回后赋值。
4.2 坑二：H5 端支付回调地址必须用公网域名
现象：微信小程序支付正常，H5 支付成功后订单状态不变。
原因：H5 支付的notify_url在代码里默认写的是window.location.origin，本地开发时是localhost:8080，微信服务器无法回调到这个地址。
解决：在后台“支付配置”里把notify_url改成你的公网域名，并且确保这个域名已经备案、配置了 SSL。本地开发时可以用内网穿透工具临时映射一个公网地址，但不要写死在代码里。
4.3 坑三：App 端打包时manifest.json的 appid 不能为空
现象：npm run build:app-plus成功，但 HBuilderX 云打包时报“appid 不合法”。
原因：萤火商城 v2.0.8 的manifest.json里appid默认是空字符串，需要你在 DCloud 开发者中心申请一个 appid 并填进去。
解决：登录 DCloud 开发者中心，创建应用后获取 appid，填入manifest.json的app-plus.distribute.google.appid字段。注意这个 appid 和微信小程序的 appid 是两回事，不要填混。
4.4 坑四：秒杀活动的库存扣减在并发下会超卖
现象：秒杀活动设置库存 100，实际卖出 103 件。
原因：萤火商城 v2.0.8 的秒杀库存扣减用的是UPDATE goods SET stock = stock - 1 WHERE id = ? AND stock > 0，这个 SQL 本身是原子的，但代码里先查了一次库存做判断，再执行 UPDATE，高并发下查和更新之间有时间差。
解决：去掉先查后扣的逻辑，直接执行 UPDATE，然后判断affected_rows是否为 1。如果为 0，说明库存不足，回滚事务。
// 正确的秒杀库存扣减 $affected = Db::name('goods') ->where('id', $goodsId) ->where('stock', '>', 0) ->dec('stock', 1) ->update(); if (!$affected) { throw new Exception('库存不足'); }4.5 坑五：分销关系绑定在用户未登录时丢失
现象：用户 A 分享链接给用户 B，B 点击链接后没有立即注册，第二天注册后分销关系没有绑定到 A。
原因：萤火商城 v2.0.8 的分销绑定逻辑是在注册时读取invite_code，但invite_code存在sessionStorage里，H5 端关闭浏览器后 sessionStorage 清空。
解决：把invite_code的存储位置从sessionStorage改成localStorage，并设置 7 天过期。同时在后端注册接口里增加一个兜底逻辑：如果请求参数里没有invite_code，尝试从 cookie 里读取。
5. 用多端版做私域商业的进阶技巧：从数据埋点到终端差异化运营
5.1 用终端标识做差异化推荐
萤火商城 v2.0.8 的X-Client-Platform不仅可以用来裁剪 API 字段，还可以用来做推荐算法的特征。微信小程序用户的分享意愿更强，H5 用户的跳出率更高，App 用户的复购率更高。你可以在后端记录每个用户的终端来源，然后在首页推荐时做差异化。
-- 在用户行为表里增加终端字段 ALTER TABLE `user_behavior` ADD COLUMN `platform` VARCHAR(20) DEFAULT '' AFTER `user_id`; -- 查询各终端的转化率差异 SELECT platform, COUNT(DISTINCT user_id) AS uv, SUM(CASE WHEN event = 'order_paid' THEN 1 ELSE 0 END) / COUNT(*) AS conversion_rate FROM user_behavior WHERE created_at > DATE_SUB(NOW(), INTERVAL 7 DAY) GROUP BY platform;这个查询能帮你快速定位哪个终端的商业价值最高。我一般会建议客户把 70% 的运营资源投在转化率最高的那个终端上，而不是平均用力。
5.2 多端版的灰度发布策略
萤火商城 v2.0.8 支持在后台配置“终端版本号”，前端请求时带上X-Client-Version，后端根据版本号决定是否返回新功能字段。这样你可以在微信小程序里先上线新功能，观察一周数据后再推给 H5 和 App。
// 前端请求拦截器：自动带上终端和版本号 uni.addInterceptor('request', { invoke(args) { args.header = { ...args.header, 'X-Client-Platform': process.env.UNI_PLATFORM, 'X-Client-Version': uni.getStorageSync('app_version') || '2.0.8' }; } });这个拦截器的关键参数是app_version，它从本地存储读取，你可以在后台配置一个“最低支持版本”，低于这个版本的请求直接返回升级提示。
5.3 一个验证多端一致性的具体技巧
多端开发最怕的是“微信小程序正常，H5 白屏”。我习惯在每次发版前跑一个一致性检查脚本：用 Puppeteer 打开 H5 页面，用miniprogram-automator打开微信小程序，分别截图首页、商品详情、购物车、订单确认四个页面，然后对比关键元素的文本内容。
# 安装检查工具 npm install puppeteer miniprogram-automator --save-dev # 运行一致性检查 node scripts/check-consistency.js --pages=home,goods,cart,order这个脚本不需要很复杂，核心是抓取每个页面的document.querySelector('.goods-price').innerText和小程序里的element.text()，对比是否一致。我靠这个脚本在发版前拦住了至少三次“H5 价格显示为 undefined”的事故。
提示：一致性检查脚本要放在 CI 流程里，每次合并到主分支自动跑，不要靠人工点。
5.4 我踩过的最大的坑：不要在多端版里用window对象
最后说一个血泪教训。萤火商城 v2.0.8 的 H5 端可以正常使用window.location，但微信小程序和 App 里没有window对象。我早期在utils/request.js里写了window.location.href来做 401 跳转，结果小程序端直接白屏。
正确的做法是用uni.navigateTo或者条件编译：
// #ifdef H5 window.location.href = '/pages/login/login'; // #endif // #ifndef H5 uni.navigateTo({ url: '/pages/login/login' }); // #endif这个坑我花了整整一个下午才定位到，因为小程序的报错信息只显示“undefined is not an object”，不告诉你具体哪一行。从那以后，我养成了一个习惯：任何涉及浏览器 API 的代码，先问自己“小程序里有没有这个对象”。希望这个习惯也能帮到你。
本文还有配套的精品资源，点击获取
