简介Jshop小程序商城是一套可用于生产环境或二次学习的开源电商系统源代码面向需要搭建微信小程序、支付宝小程序、公众号/H5及APP商城的中小企业和PHP开发者解决商城系统从0到1的搭建与多端统一管理问题。后台采用ThinkPHP5.1框架核心功能包括商品管理、订单流程、会员体系、营销工具和DIY可视化装修前端覆盖多端入口代码组织清晰便于按业务模块进行裁剪和扩展尤其适合快速落地移动电商MVP或做深度定制也为后续迭代提供了清晰的扩展点。压缩包约108.18MB上游暂未提供文件总数与类型明细内容以PHP源码、小程序前端页面及配置代码为主。已有248人学习适合PHP初中级开发者、产品运营及承接商城类项目的技术团队部署后可重点参考其路由结构、数据库设计及多端接口封装方式。1. Jshop 小程序商城DIY 可视化解决的开发痛点一个电商小程序从 0 开始做商品、购物车、订单、支付、后台管理这几个模块团队排期压到两个月都算快的其中首页和各频道页反复调 UI、适配不同机型又能吃掉三分之一工期。Jshop 是带 DIY 可视化装修能力的商城源代码——后台拖拽配置、小程序端按数据渲染整个「页面装修」环节从开发任务变成配置任务。这篇文章只聊实战它的代码结构怎么拆、本地怎么一次跑通、DIY 配置从后台到小程序端的链路怎么走、哪些坑最耽误人。适合正在选型、想拿现成源码快速交付商城项目或做二次开发的人。2. 拆解 Jshop 源码ThinkPHP 后端与小程序前端怎么分工协作2.1 整体架构与目录约定Jshop 是典型的三段式管理后台、API 接口、小程序前端。后端基于 ThinkPHP 5 那一代的主流写法管理后台由 PHP 渲染页面小程序端不依赖后台页面只通过 HTTP 接口取 JSON。拿到源码先看目录模块边界一眼就清楚jshop/ ├── application/ │ ├── admin/ # 管理后台模块登录、商品、订单、装修 │ ├── api/ # 小程序数据接口模块控制器只输出 JSON │ ├── common/ # 公共模型、服务层、常量与函数 │ └── route.php # 路由规则API 路径别名在这改 ├── public/ # Web 根目录Nginx 的 document root 指到这里 │ ├── index.php # 单一入口文件 │ ├── static/ # 后台 CSS/JS │ └── uploads/ # 商品图、装修图等本地上传文件 ├── thinkphp/ # 框架核心不建议动 └── install/ # 安装向导相关重点说public。整个项目只有这个目录是 Web 根目录Nginx 必须把它设成root。很多新手把站点根目录指到 jshop 项目根目录导致 application 下的 PHP 文件能被直接访问这是明显安全隐患。我一般会先确认 rewrite 只对 public 生效再把 application、thinkphp 目录的外部访问权限拦掉。同时后台和 API 的入口都是 public/index.php框架按 URL 分发到 admin 或 api 模块所以改路由别名时不要动入口文件。2.2 后端模块划分与商城核心表application/admin 下按业务功能拆控制器Goods、Order、User、Page、Setting 等application/api 下的控制器按小程序端的请求场景拆比如 Index、Goods、Cart、Order、Pay。api 控制器里很少出现模板赋值基本就是查库、组数据、return json。以商品详情为例// application/api/controller/Goods.php namespace app\api\controller; use think\Db; class Goods { public function detail() { // input(参数名, 默认值, 过滤规则)二开新增接口时别漏过滤 $goodsId input(goods_id, 0, intval); $goods Db::name(goods)-where(goods_id, $goodsId)-find(); if (!$goods) { return json([status 0, msg 商品不存在]); } // 组装 SKU 列表小程序端按这个结构渲染规格选择 $skuList Db::name(goods_sku) -where(goods_id, $goodsId) -select(); $goods[sku_list] $skuList ?: []; return json([status 1, data $goods, msg success]); } }这段代码反映了两个约定第一接口统一返回{status, data, msg}status 1 表示业务成功小程序端只看这个字段不看 HTTP 状态码第二所有外部参数必须过过滤intval、trim属于最低要求。很多二开安全问题出在把参数直接拼进 where 条件新写的接口最容易犯。商城核心表大致是这几张表名作用关键字段goods商品主表goods_id, goods_name, price, stock, is_on_salegoods_skuSKU 规格sku_id, goods_id, spec_keys, stock_pricecart购物车cart_id, user_id, goods_id, numsorder订单主表order_id, order_sn, user_id, pay_status, ship_statususer会员表user_id, nickname, mobile, balancepage装修页面配置page_id, type, items_jsonsetting全局配置key, value不同版本的表名可能略有差异但page表里的items_json是 DIY 装修的核心后面第 4 章会专门展开。做二次开发时我习惯先开 TP5 调试模式页面底部能看到当前请求查了哪些表、走了哪些 SQL比打断点快得多。顺着「小程序页面 → api 控制器 → 模型 → 表」这条链路走一遍一个新模块的代码归属基本就清楚了。2.3 小程序端目录与 API 请求封装小程序工程是原生微信小程序写法pages 放页面、utils 放公共工具、components 放自定义组件。所有接口请求集中在 utils 下的 request 封装里改接口域名只动一个文件// utils/request.js const API_BASE_URL https://你的域名/index.php/api; function request(url, method GET, data {}) { return new Promise((resolve, reject) { wx.request({ url: API_BASE_URL url, method: method, data: data, header: { Content-Type: application/json }, success: (res) { // 业务成功看 status不是看 HTTP 200 if (res.data.status 1) { resolve(res.data.data); } else { wx.showToast({ title: res.data.msg || 请求失败, icon: none }); reject(res.data); } }, fail: (err) reject(err) }); }); } module.exports request;这 30 多行里藏着三个联调关键点第一API_BASE_URL 写死如果小程序能编译但数据不对先确认这个变量指向的环境第二status 1 是业务成功约定很多新手只看 HTTP 200结果 status0 时继续往下执行出现「页面没数据但也不报错」的怪问题第三fail 回调只管网络层错误真正的业务错误提示在 success 分支里所以调试时优先看返回 JSON 的 msg 字段。小程序端的 components 目录对应 DIY 组件类型比如 banner、nav、goods-list 各占一个子目录。后面第 4 章会讲清楚组件数据怎么流转。先记一条主链路小程序请求 page 接口 → 拿到 items_json → 渲染页面组件。这条链路通了Jshop 的 DIY 可视化就算看懂了一半。3. 本地跑通 Jshop环境、安装、联调一次过3.1 环境要求与安装前检查Jshop 的部署要求不复杂但版本坑很明确。PHP 版本不能太新也不能太旧。我常用的稳定组合是 PHP 7.0~7.2 MySQL 5.7 Nginx 1.16如果你机器只有 PHP 8.0直接跑 TP5 时代的代码大概率会遇到函数被移除导致的致命错误最省事的办法是装一个多版本 PHP 切换工具单独给 Jshop 切到 7.2。环境项推荐配置说明PHP7.0 ~ 7.2TP5 时代代码8.x 下容易白屏MySQL5.7 或 8.08.0 需把认证插件改为 mysql_native_passwordWeb 服务器Nginx 1.16Apache 也可但伪静态规则不同小程序工具微信开发者工具稳定版编译和真机预览用操作系统Linux / Windows / macOS本地跑通不限系统MySQL 8.0 不是不能用但老版本驱动的连接方式默认不兼容 caching_sha2_password我遇到过几次「数据库安装正确但项目连不上」的怪问题最后都是把用户认证插件改回 mysql_native_password 解决的。如果只是本地验证直接用 5.7 最省心。3.2 数据库导入与配置文件修改先在 MySQL 里建库再导入源码自带的 SQL 文件。我习惯用命令行导入图形工具导入大文件时中途卡死的情况遇到过太多次mysql -uroot -p -e CREATE DATABASE IF NOT EXISTS jshop DEFAULT CHARSET utf8mb4; mysql -uroot -p jshop jshop.sql第二步导入如果报错多半是当前库里已经有同名表尤其当表前缀都是 jshop_ 时容易重复。导入成功之后修改数据库配置// application/database.php return [ type mysql, hostname 127.0.0.1, database jshop, username root, password 你的密码, hostport 3306, prefix jshop_, charset utf8mb4, ];prefix是表前缀。如果 SQL 文件里表名是jshop_goods这里就填jshop_模型里Db::name(goods)最终查的是jshop_goods。排查「表不存在」报错时先核对这个 prefix 和库里的实际表名是否一致。另外如果项目里同时存在 .env 文件database.php 里的值可能被 .env 覆盖改配置前先确认哪个生效。3.3 配置伪静态与访问后台Nginx 的站点配置是本地跑通的关键环节。常见做法是新建一个 server 块把域名指到开发机server { listen 80; server_name yourdomain.com; root /var/www/jshop/public; index index.php index.html; location / { if (!-e $request_filename) { rewrite ^(.*)$ /index.php?s$1 last; } } location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_pass unix:/var/run/php/php7.2-fpm.sock; } }三个易错点root 一定指到 public 目录rewrite 规则用if (!-e $request_filename)是兼容性最好的写法等价于 try_filesfastcgi_pass 的 socket 路径要和你装的 PHP 版本对上。伪静态没配好最典型症状是首页能开、二级页面 404 或 500。3.4 小程序端编译与接口联调小程序工程里的接口地址一般在 utils/config.js把 baseUrl 先改成你电脑的局域网 IP例如http://192.168.1.100/index.php/api。然后用微信开发者工具导入项目在「详情」设置里勾选「不校验合法域名」。真实上线时必须用 HTTPS 域名并且在微信公众平台后台配置 request 合法域名。本地联调时可以用 curl 先验证后端是否通了curl http://127.0.0.1/index.php/api/index/index如果返回 JSON 且 status1说明后端链路正常问题就收敛在小程序端配置。真机预览时不要用http://localhost手机访问不到你电脑上的 localhost要用局域网 IP同时检查系统防火墙是否放行了 80 端口。3.5 常见安装报错速查现象大概率原因处理动作访问后台整屏白页PHP 版本过高或 display_errors 关闭切 PHP 7.2开 display_errors 看具体报错二级页面 404伪静态未配置检查 rewrite 规则和 server_name表不存在表前缀不匹配或数据库没导入全核对 prefix 和 SQL 导入过程小程序端请求失败域名校验问题或非 HTTPS本地关校验线上配 HTTPS图片打不开站点 URL 配错或 uploads 权限后台设置里改线上域名确认 uploads 可读写上面这些是安装期最容易碰到的问题。如果照着做还卡住最快的方式是开 PHP 错误日志看 runtime/log 目录下的当天日志文件报错信息里通常直接写着文件和行号。4. DIY 可视化装修全链路后台拖拽怎么变成小程序页面4.1 组件类型与 JSON 数据结构DIY 可视化的核心不是「拖拽」的交互效果而是「每个组件的数据结构是否稳定」。后台每次拖入一个组件生成一条 JSON 记录包含两层信息type 表示组件类型props 是该组件的配置项。后台能编辑、接口能回传、小程序端能渲染三方各改各的还能对上靠的就是这套 JSON 约定。{ items: [ { type: banner, props: { height: 180, images: [ { src: /uploads/banner-01.jpg, link: /pages/goods/detail?goods_id1 } ] } }, { type: nav, props: { columns: 4, items: [ { icon: /uploads/nav-01.png, title: 品牌馆, link: /pages/brand/list } ] } }, { type: goods_list, props: { category_id: 12, layout: oneRow, limit: 10 } } ] }banner 是轮播图、nav 是导航宫格、goods_list 是商品列表。注意 goods_list 不需要把商品数据存在 JSON 里只存 category_id 和 limit小程序端请求接口时动态拉取。这样后台改一个分类前台商品立刻变同时避免装修接口返回超长 JSON 的性能问题。常见组件类型还包括 ad、article 等规则一致。4.2 装修数据存储与后台保存流程后台点保存时整个页面 items_json 会写进 page 表。小程序端进入页面时请求 page 接口拿到 items_json再根据组件类型动态请求对应数据。这里有个容易踩的坑items_json 是 JSON 文本数据库字段如果设计成 varchar(255)装修组件一多直接截断。所以我会在部署后先确认字段类型ALTER TABLE jshop_page MODIFY items_json TEXT COMMENT 页面装修配置JSON;如果项目已经跑了一段时间直接执行这条语句避免后台多拖几个组件后保存失败。保存流程在控制器里大致是接收整个装修 JSON → 校验合法性 → 入库存字符串 → 清页面缓存。清缓存经常被漏掉导致前台永远显示旧数据下面是一个典型的保存方法public function savePage() { $pageId input(page_id, 0, intval); $itemsJson input(items_json, , trim); // 先 decode 一次校验是否合法 JSON避免脏数据入库 $arr json_decode($itemsJson, true); if ($arr null) { return json([status 0, msg 装修数据格式错误]); } Db::name(page)-where(id, $pageId)-update([ items_json $itemsJson ]); // 重要清掉装修页缓存否则前台读旧数据 cache(page_ . $pageId, null); return json([status 1, msg 保存成功]); }缓存 key 规则不同版本可能不一样二开时我会把「读装修缓存」和「写装修缓存」统一封装到同一个服务类里以后清理只改一处避免出现 5.4 里的「保存了但看不到效果」。后台编辑器里组件配置表单由一组 JS 配置驱动。大致结构是这样// admin/js/diy-editor.js 简化示意 const componentConfigs { banner: { label: 轮播图, form: [ { key: height, label: 图片高度, type: number }, { key: images, label: 轮播图片, type: imageGroup } ] }, nav: { label: 导航宫格, form: [ { key: columns, label: 列数, type: number } ] }, goods_list: { label: 商品列表, form: [ { key: category_id, label: 商品分类, type: categoryPicker }, { key: limit, label: 显示数量, type: number } ] } };这套配置驱动表单生成后后台新增一个组件类型只需要注册一份 config再在小程序端写一个对应渲染组件即可。理解了这套机制就知道扩展 DIY 组件不是玄学是前后端两头各自加配置的问题。4.3 小程序端页面动态渲染的代码路径小程序端拿到 page 接口返回的 items 数组后先给每一项补一个唯一 id供 wxml 的 wx:key 使用避免列表渲染告警Page({ data: { items: [] }, onLoad() { request(/page/home).then(res { const items res.map((item, index) { return { _id: index, ...item }; }); this.setData({ items }); }); } });然后在 wxml 里按 type 分发到不同模板或组件block wx:for{{items}} wx:key_id template wx:if{{item.type banner}} isbanner data{{props: item.props}} / template wx:elif{{item.type nav}} isnav data{{props: item.props}} / template wx:elif{{item.type goods_list}} isgoodsList data{{props: item.props}} / /blockbanner、nav 这类纯展示组件直接用 props 渲染。goods_list 组件需要在 attached 生命周期里根据 props 去请求商品接口Component({ properties: { props: { type: Object, value: {} } }, data: { goodsList: [] }, lifetimes: { attached() { this.loadGoods(); } }, methods: { loadGoods() { const { category_id, limit } this.props; request(/goods/list?category_id category_id limit limit) .then(res { this.setData({ goodsList: res.list }); }); } } });一个页面里放多个 goods_list 组件时它们各请求各的互不影响这是组件化的天然优势。但组件多了以后首屏会同时发出十几个请求并发过高。我在实际项目里会把首页所有组件的动态数据合并成一个聚合接口首屏只发一次请求。这个改造不复杂收益却非常明显页面加载速度能快一倍以上。5. Jshop 二次开发避坑指南五个高频问题与排查路径5.1 安装完成后整站白屏现象安装步骤正常访问后台或首页就是白屏浏览器按 F12 只看到 500 错误或者什么都没返回。原因整站白屏大概率是 PHP 版本过高。TP5 时代的代码用到的高版本已移除的内置函数白屏是 Fatal error 在 display_errors 关闭状态下的表现。排查第一步是把 display_errors 打开或者直接看 PHP-FPM 的错误日志如果日志里出现 each()、create_function() 这类报错基本可以确定是版本问题。另一个次常见原因是 public/index.php 文件权限异常或者上传时文件名被改动。解决切到 PHP 7.2调整 Nginx 的 fastcgi_pass 指向对应 socket。打开 display_errors 能看到具体是哪个文件哪一行报错定位后手动兼容掉。这种兼容修改只改业务代码不动 thinkphp 框架核心。顺利的话几分钟内就能从白屏恢复到正常页面。5.2 商品图上传后前端图片全部裂掉现象后台上传商品图提示成功小程序端商品图片和装修图全部打不开浏览器直接访问图片地址也 404。原因图片 URL 拼接问题。本地上传文件存在 public/uploads 下接口返回的图片路径通常是相对路径 /uploads/xxx.jpg小程序端展示时需要补上站点域名。如果后台「商城 URL」配置项填的是 localhost手机端拿到的就是http://localhost/uploads/...当然打不开。其次是 uploads 目录权限不对PHP 进程没有写权限上传返回成功但文件实际没落盘。解决后台设置里把站点 URL 改成线上真实域名然后确认 uploads 目录有写入权限。如果图片放到第三方存储检查存储配置里的访问域名是否和文件实际域名一致并注意微信小程序端对图片资源有 HTTPS 要求HTTP 图片会被拦截。排查时先看数据库里存的图片路径是相对路径还是完整 URL再决定是改配置还是改接口统一拼接。5.3 小程序请求接口一直转圈现象小程序编译正常进入首页后一直 loading开发者工具的 Network 面板显示请求失败或者请求成功但返回内容无法解析。原因最常见是本地开发时没关闭合法域名校验或者接口地址是 http 而非 https。其次PHP 接口返回了非 JSON 内容比如代码里混入 PHP Notice 警告wx.request 虽然收到响应但解析 JSON 失败同样表现为请求失败。解决本地调试在微信开发者工具「详情」中勾选「不校验合法域名」同时用 curl 直接访问接口确认返回的是纯 JSON。如果响应里混了 PHP Notice去 php.ini 把 error_reporting 调低或把 display_errors 关掉。真实上线时必须在微信公众平台配置 request 合法域名否则正式版小程序一样会转圈。这个问题排查路径固定先分清楚是网络层失败还是 JSON 解析失败能节省大量时间。5.4 装修保存后小程序端还是旧页面现象后台 DIY 装修拖拽、保存都提示成功但小程序端页面纹丝不动过几分钟再看还是旧内容。原因不是数据没保存是缓存。页面装修这种高频读取、低频写入的数据在 Jshop 里通常会走文件缓存。后台改了 items_json前台接口读到的却是旧缓存。我至少三次被这个坑卡住每次都是「明明存了」的错觉实际上数据在数据库里已经变了读的时候被缓存挡了一道。解决保存装修的控制器方法里调用清理缓存的方法或者在后台装修页面列表手动刷新缓存。排查时可以直接删除 runtime 目录下的缓存文件如果页面立刻变化就说明是缓存写入时机的问题去检查保存逻辑里有没有清缓存。二开时建议把装修读写的缓存 key 统一封装避免多个地方各写各的 key清理起来很麻烦。5.5 支付成功后订单没有回写状态现象微信支付显示扣款成功但后台订单状态还是「待付款」用户付款后小程序端也看不到已支付状态。原因支付回调不生效。微信支付成功后微信服务器会向商户平台配置的回调地址发通知Jshop 在回调里验签、更新订单状态。回调地址被防火墙拦截、回调域名未备案、或验签密钥配置错误都会出现「钱扣了、订单没变」的情况。本地调试时更常见的是回调地址写成了 localhost微信服务器根本访问不到。解决先看微信商户平台里的回调记录确认微信有没有发起回调。有回调但失败去 Jshop 的支付日志看具体报错没有回调检查商户平台配置的 notify_url 是否外网可访问。本地调试时可以用接口调试工具把微信的回调报文手动 POST 到本地回调地址单独验签逻辑。注意回调地址必须是外网能访问的 HTTPS 地址临时联调可以用内网穿透工具映射一个测试域名但不能拿测试域名上生产。6. 把 Jshop 用到生产接口鉴权、缓存分层与部署姿态到这里Jshop 能不能用已经不是功能问题而是「你敢不敢让它上生产」。我见过太多案例本地跑得欢一上线就暴雷。下面三件事是我在交付项目前一定会做的。第一接口鉴权不能全裸奔。Jshop 默认很多商品、分类接口是公开的但涉及用户信息和订单查询的接口必须校验登录态。小程序端用 wx.login 换 code后端通过 code2session 拿到 openid 再换业务 token后续请求在 header 里带上 token后端用中间件统一校验。不要在单个接口里手动校验因为新功能一多很容易漏写出问题就是越权访问。第二缓存要分层。上线初期流量不大TP5 默认文件缓存够用。但首页和装修接口是高并发热点我会加一层 Redis 缓存接口先查 Redis没有再查数据库并回填。缓存 key 设计成 page_id 版本号后台装修保存时递增版本号前台读取时自动拿到新数据从根上绕开 5.4 那个「保存了看不到变化」的坑。第三业务边界要提前确认。Jshop 是单商户商城源码不支持多商户、分销裂变这类平台级玩法。判断它够不够用不是看功能列表而是看你项目里有没有「多角色、多店铺、分账」这样的硬需求。单店铺卖货Jshop 加上定制二开完全够如果客户要平台模式这个方向的改造成本接近重写不如一开始换方案。我在每次交付前养成的习惯是把接口全部抓一遍请求日志确认没有重复请求和慢查询再把后台 DIY 装修页面从空页面开始重建一次确保不是只会在已有配置上改。整条链路摸透了之后Jshop 反而比很多商业 SaaS 好用因为所有代码都在你手里页面渲染、缓存时机、接口数据结构都能自己把控。希望今天的拆解能帮到你。本文还有配套的精品资源点击获取