简介：一份基于PHP开发的开源电商系统ShopXO源码包，面向PHP开发者、电商二次开发人员及希望搭建商城的技术学习者。源码完整覆盖商品、订单、支付、购物车、用户、物流等核心模块，适合研读MVC分层结构、数据库设计、支付API对接、前端交互与安全防护等关键知识点，也可直接用于功能二次扩展。
压缩包为zip格式，共5206个文件，大小约37.76MB。文件类型以php业务逻辑、js交互脚本、html页面、css样式、json配置为主，同时包含png/gif/jpg图片素材、wxml/ttml/axml等多端小程序文件、sql数据库脚本及md说明文档，整体兼顾Web端与小程序场景，便于对照学习。
已有998人学习浏览。通过源码可深入理解商品分类与搜索、购物车与订单状态流转、支付接口集成、物流配送追踪、模板引擎使用及后台权限控制的具体实现，还可学习缓存机制、数据库索引优化等性能处理思路，适合按模块逐层拆解和改造实践。
1. ShopXO 商城系统源码：它到底能拿来做什么
想快速上线一个能卖货的 B2C 商城，与其从零写一套，不如找一份成熟的 PHP 商城源码做二次开发。ShopXO 就是这种源码建站里出镜率较高的一个：PHP 语言、MySQL 存储、后台功能完整，PC、H5、小程序、App 共用同一套数据和接口。对线下门店、无人值守便利店这类业务来说，拿到 ShopXO 商城系统源码部署到自己的服务器上，商品、订单、会员、支付这些数据都握在自己手里，比被 SaaS 平台抽成、限流要踏实。
它适合两类人。一类是要做独立商城、不想被平台规则绑住的运营团队，买不起商业授权时可以先用开源版把商业模式验证跑通；另一类是 PHP 开发者，想找一份能读懂的商城系统源码，把路由、控制器、模型、模板、钩子这一整套 MVC 流程通读一遍。下面按「部署、读码、二次开发、上线排错」的顺序，把走通这套源码的关键步骤、参数和坑一次说清。
2. 部署 ShopXO 商城源码：环境准备与最小安装
第一次拿到源码包，先别急着配 Nginx。我一般会先在本地用 PHP 内置服务器把它跑起来，验证压缩包完整性、目录结构是否齐全，再考虑正式建站。这条路线覆盖从环境检查、启动服务、配置伪静态到完成安装向导的全过程，每一步卡住都能在当前环节直接定位。
2.1 跑 ShopXO 之前先搞清楚的三件事
第一，这套商城系统源码是 PHP 源码，不是纯静态 HTML，服务器上必须先有 PHP 解释器和 MySQL，安装向导会做一次完整的环境检测，PHP 版本、扩展缺失都会在这个环节被卡住。第二，PC、小程序、App 多端共用同一份数据和后台，部署时只需要把源码放一份，其余端通过 API 访问这台服务器，不需要为每个端各装一套。第三，正式上线必须配置伪静态和可写目录，否则商品详情页会 404，后台上传图片会静默失败。
2.1.1 环境要求参考
| 项目 | 参考要求 | 说明 |
|---|---|---|
| PHP | 7.x，建议 7.4 | 需启用 curl、gd、pdo_mysql、openssl、fileinfo 扩展 |
| MySQL | 5.6 及以上 | 建议 5.7，建表时默认使用 utf8mb4 字符集 |
| Web 服务器 | Nginx / Apache | Nginx 需要能写伪静态规则，Apache 需要开启 mod_rewrite |
| 操作系统 | Linux 为主 | Windows 本地开发也能跑，但目录权限逻辑不同 |
提示：正式部署不要用 PHP 5.6 以下的版本，ThinkPHP 框架底层的语法和安全性都跟不上，遇到报错也很难在网上找到有效答案。
2.2 用 PHP 内置服务器快速验证源码
拿到源码后，先做一次最小化验证。进入源码根目录，确认public目录存在，然后启动 PHP 内置服务器。
# 进入源码根目录 cd /path/to/shopxo # 用 PHP 内置服务器启动，-t 指定 Web 根目录为 public # 0.0.0.0 表示监听所有网卡，方便同一局域网内联调 php -S 0.0.0.0:8080 -t public # 浏览器访问安装向导 # http://127.0.0.1:8080/install.php-S参数指定监听地址和端口，-t指定 docroot。把站点根目录指向public而不是源码根目录，是为了避免application、config、runtime这些目录被 Web 直接访问。内置服务器启动后能打开install.php，说明 PHP 环境和源码文件都正常。这一步最常见的报错是提示缺少某个扩展，看终端输出即可定位。内置服务器只用于本地验证和开发，它单进程处理请求，并发稍高就阻塞，上线必须换成 Nginx 或 Apache。
2.3 正式建站的 Nginx 伪静态与目录权限
进入正式部署时，Nginx 的配置重点有两个：站点根目录指向public、写对伪静态规则。下面这份配置是我在服务器上常用的最小可用版本。
server { listen 80; server_name your-domain.com; # 根目录必须指向 public，而不是源码根目录 root /data/www/shopxo/public; index index.php index.html; # 伪静态：请求的文件或目录不存在时，重写到 index.php location / { if (!-e $request_filename) { rewrite ^(.*)$ /index.php?s=$1 last; } } # PHP 请求交给 fastcgi 处理 location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } }伪静态规则的核心是rewrite ^(.*)$ /index.php?s=$1 last;，它把「看起来像真实路径」的 URL 转成 ThinkPHP 的路由参数。很多商城页面打不开，原因就是if (!-e $request_filename)这行没写对，静态资源请求也被转发到了 PHP 解析器，导致 CSS、JS 直接输出 404 或源码。SCRIPT_FILENAME必须用$document_root拼接，否则会报「No input file specified」。
目录权限方面，runtime目录必须允许 PHP 进程写入，用于缓存、日志和编译模板。常见做法是：
# 目录归属改为运行用户，例如 www chown -R www:www /data/www/shopxo # 目录权限 755，文件权限 644 find /data/www/shopxo -type d -exec chmod 755 {} \; find /data/www/shopxo -type f -exec chmod 644 {} \; # runtime 目录单独放开写权限 chmod -R 775 /data/www/shopxo/runtime不要把整个目录直接chmod 777。777 意味着任何系统用户都能写这些文件，一旦服务器上有其他站点被入侵，对方就能直接改写源码执行任意代码。
2.4 安装向导的参数填法与常见拦截
访问install.php后，向导会先做环境检查，然后让你填数据库信息。这里每个参数都值得确认一遍，因为很多人在这一步填错，导致安装完成后所有页面都报数据库连接错误。
| 表单项 | 参考值 | 填错会怎样 |
|---|---|---|
| 数据库主机 | 127.0.0.1 | 数据库在其他机器时填内网 IP，填 localhost 会走 socket 连接而失败 |
| 数据库端口 | 3306 | 端口不一致直接连不上，报 2002/2003 错误 |
| 数据库名 | shopxo | 这个库需要先创建好，一般不会自动建库 |
| 数据表前缀 | shopxo_ | 多个商城共用一库时用来隔离，同一套源码装两份别用相同前缀 |
| 管理员账号密码 | 自定义 | 安装完成后立即登录后台修改，弱口令很容易被扫描器爆破 |
提示：安装完成后，建议删除
public/install.php或限制访问。否则别人重复访问安装向导，理论上可以覆盖配置、重置管理员密码，这是源码部署里最容易忽略的安全收尾动作。
整个安装过程大约一分钟。如果卡在环境检测环节，优先检查 PHP 扩展是否符合要求；如果卡在数据库连接，先用命令行mysql -h127.0.0.1 -P3306 -u用户名 -p手动验证账号能否登录。
3. 读透 ShopXO 商城源码结构：二开先改哪里
部署跑通只是开始，真正的工作量在二次开发。我见过不少人拿到这套商城系统源码直接全局搜索「价格」两个字，然后拼命改模板，结果后台一更新数据，改动全被覆盖。原因是没搞清源码里的层级：控制器负责取数，模型负责查表，模板只负责渲染。下面把二开前必须读懂的目录结构和扩展机制过一遍。
3.1 application 目录：业务逻辑主干
源码根目录下的application目录是核心，按模块拆分成多个子目录。用tree -L 1看一层就够了：
# 查看 application 目录顶层结构 tree -L 1 application/输出大致对应后台管理、前端页面、接口、公共逻辑这几个部分。我这边的划分方式如下，供参考。
| 目录 | 职责 | 二开时改哪里 |
|---|---|---|
admin | 后台控制器和视图 | 后台功能扩展、菜单调整 |
index | 前端页面控制器 | 页面路由、商品展示逻辑 |
api | 多端接口逻辑 | 小程序和 App 的接口逻辑 |
common | 公共函数、模型、状态配置 | 全站共用方法、状态枚举 |
install | 安装向导 | 环境检测逻辑，一般不动 |
规则很简单：URL 里的模块名对应application下的目录名，控制器对应controller目录里的类文件，方法名对应控制器里的 public 函数。比如访问首页商品列表，路由指向index模块的某个控制器方法；改这个列表的取数逻辑，去application/index/controller下面找对应文件即可，不用碰模板，也不用碰后台。
3.2 主题机制：改页面不动内核
改页面是二开里最频繁的需求，ShopXO 这类源码会把页面模板独立出来，和业务逻辑分开。主题目录一般放在public下或独立 themes 目录，后台可以切换主题。二开时如果只是调整样式和页面结构，优先改主题文件，不要动控制器代码。
模板文件里的语法是 ThinkPHP 模板引擎，常见的输出方式是这样的：
<div class="goods-item"> <a href="{:url('index/goods/detail', ['id' => $goods['id']])}"> <img src="{$goods.images}" alt="{$goods.title}"> </a> <p class="shopxo-price">{$goods.price}</p> </div>{:url(...)}是路由生成函数，第一个参数是模块/控制器/方法路径，第二个参数是查询参数。{$goods.images}是变量输出，变量名要跟控制器 assign 给模板的键名一一对应。改模板时如果发现某个字段没显示，不要猜，回到控制器查看它往模板里传了哪些变量。
这里最容易踩的坑是缓存。ThinkPHP 会编译模板文件，改完页面不生效时，清掉runtime目录下由模板编译生成的缓存文件即可，我一般直接删掉整个runtime目录让它自动重建。
3.3 钩子与插件：不破坏源码的扩展方式
直接在源码里加功能最省事，但也最危险，以后官方升级、修补漏洞时你的改动全会被覆盖。更稳妥的做法是用钩子机制，在不动内核的前提下挂载自己的业务逻辑。ShopXO 的钩子需要先注册监听，一般在config目录的 listens 配置里声明事件和处理类对应关系，类似这样：
// config/listens.php 的一部分，示意钩子注册格式 return [ // 订单支付成功事件 'order_pay_success' => [ 'app\\common\\logic\\OrderPaySuccess' , 'app\\plugins\\coupon\\hook\\OrderPaySuccess' , ], ];事件名对应业务代码里触发钩子的位置，值是一个数组，数组里每一项都是一个带handle方法的类。业务代码执行到订单支付成功时遍历这个数组，按顺序调用每个类的处理逻辑。用这种方式加功能，升级源码时只需要保留插件目录和配置，不用重新合并代码。
我建插件目录时习惯保持「每个插件一个独立文件夹」的结构，里面至少要有钩子方法文件、后台配置页面、安装和卸载逻辑。这样单个插件出问题，直接移除监听并删除目录即可回滚。
4. 对接多端 API 与业务扩展实战
小程序、App、H5 要共用一套商城系统源码，靠的是 API 接口层。这一章先把接口鉴权的原理讲透，再给出一个可以直接改的 PHP 客户端，最后用一次实际业务扩展把钩子机制完整串起来。很多人二开卡住，就是这三件事没理顺：能调到接口自测，知道怎么新写接口，知道怎么把扩展逻辑挂到已有业务上。
4.1 拿到商城 API 的第一件事：跑通鉴权
多端接口不能裸奔，否则任何人都能调你的商品、订单接口。常见的做法是给每个端分配一个应用标识，然后对请求参数做签名校验。核心思路：客户端用私钥对参数排序拼接后计算签名，服务端用同样算法重算一次；两个签名一致才放行。
| 参数名 | 示例值 | 作用 |
|---|---|---|
app_key | wx1234567890 | 区分是哪个端在请求 |
timestamp | 1710000000 | 防止请求重放，服务器一般拒绝超过 5 分钟的老请求 |
sign | 32位md5字符串 | 对全部请求参数加密钥计算得到 |
version | v1 | 接口版本，后续变更不影响老端 |
签名规则在不同源码实现里会有差异，具体算法以你拿到的这套为准，但大体流程相同。记住一个原则：密钥只存在服务器端和你的客户端代码里，绝不能通过接口下发；参数排序必须用字典序，这样两端的拼接顺序才能保持一致。
4.2 用 PHP 写一个对接 ShopXO API 的最小客户端
下面是一个可以复制到任意 PHP 项目里的最小客户端，包含参数排序、签名生成和请求发送：
<?php class ShopxoApiClient { private string $baseUrl; private string $appKey; private string $appSecret; public function __construct(string $baseUrl, string $appKey, string $appSecret) { $this->baseUrl = $baseUrl; $this->appKey = $appKey; $this->appSecret = $appSecret; } public function get(string $path, array $params = []): array { $params['app_key'] = $this->appKey; $params['timestamp'] = time(); $params['sign'] = $this->sign($params); $url = rtrim($this->baseUrl, '/') . '/' . ltrim($path, '/'); $ch = curl_init($url . '?' . http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $response = curl_exec($ch); curl_close($ch); return json_decode($response, true) ?: []; } private function sign(array $params): string { // 只保留参与签名的参数，签名本身不参与 unset($params['sign']); // 按字典序排序，保证两端拼接顺序一致 ksort($params); // 按 key=value 拼接，末尾追加密钥后取 md5 $str = urldecode(http_build_query($params)) . $this->appSecret; return md5($str); } } // 用法示例 $client = new ShopxoApiClient( 'http://your-domain.com', 'wx1234567890', 'your-app-secret' ); $goodsList = $client->get('api/goods/index', ['page' => 1, 'limit' => 20]);ksort按字典序排序参数，这是签名算法里最容易踩坑的地方，数组里只要多一个未参与排序的参数，服务端重算的签名就对不上。urldecode(http_build_query($params))先把参数转成key=value拼接格式，再反转义，防止中文字符和特殊符号编码不一致导致签名差异。拿到 JSON 响应后必须判断业务码，即使 HTTP 状态码是 200，也可能返回「参数错误」这样的业务失败结果。
4.3 扩展一个限时折扣插件：从建表到钩子
假设现在业务方需要一个「限时折扣」功能，商品详情页要展示折扣价。最干净的做法是独立一张表存折扣数据，再用钩子把折扣价合并到商品详情返回结果里。先建表：
-- 限时折扣表 CREATE TABLE `shopxo_flash_sale` ( `id` int(11) NOT NULL AUTO_INCREMENT, `goods_id` int(11) NOT NULL COMMENT '商品ID', `sale_price` decimal(10,2) NOT NULL COMMENT '折扣价', `start_time` int(11) NOT NULL COMMENT '开始时间戳', `end_time` int(11) NOT NULL COMMENT '结束时间戳', `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '1启用 0禁用', PRIMARY KEY (`id`), KEY `idx_goods_id` (`goods_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='限时折扣表';时间字段用int存时间戳，比datetime更适合做范围判断，避免时区转换带来的边界问题。然后在钩子回调里写取折扣价格的逻辑：
// 钩子回调：根据商品ID读取正在进行的限时折扣 function getFlashSalePrice(int $goodsId) { $now = time(); // 使用 ThinkPHP 查询构造器 $row = Db::name('flash_sale') ->where('goods_id', $goodsId) ->where('start_time', '<=', $now) ->where('end_time', '>=', $now) ->where('status', 1) ->order('id desc') ->find(); return $row ? (float)$row['sale_price'] : null; }条件start_time <= 当前时间 <= end_time才是「正在生效」的折扣，漏掉任意一个边界都会出现还没到点就打折、过了点还在打折的情况。这里在钩子回调里返回null就维持原价，返回具体金额则覆盖原价。接入位置在商品详情控制器里查询到$goods数组后、模板渲染之前。
5. 上线前的自检脚本与两个高频坑
部署完成、二开测完，真正决定能否睡个好觉的是上线前这一轮自检。下面这几个动作加起来不到一分钟，能提前暴露大部分生产环境才出现的问题。
5.1 一条命令把环境自检跑完
# 检查 PHP 版本 php -v # 检查必需扩展是否加载 php -m | grep -E 'curl|gd|pdo_mysql|openssl|fileinfo' # 检查 runtime 目录是否可写 test -w runtime && echo 'runtime writable' || echo 'runtime NOT writable' # 检查配置缓存目录 test -w config && echo 'config writable' || echo 'config NOT writable'扩展检查里如果缺少fileinfo，有些上传和文件处理功能会在运行时才报错，安装向导当时未必能发现。目录是否可写也不能只看是不是 755，要看运行 PHP 的用户是否真的有权限，用ps aux | grep php-fpm确认当前运行用户，再看看目录属主是不是这个用户。
5.2 伪静态 404 与商品图商品图不显示的定位思路
商品页面 404 十有八九是伪静态规则没生效。先确认 Nginx 配置文件里rewrite ^(.*)$ /index.php?s=$1 last;存在于location /内而不是location = /这种精确匹配块里；再确认fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;没有被重复覆盖成别的路径。改完配置执行nginx -t && nginx -s reload，再刷新页面。
商品图片不显示则是另一类问题。前后台能登录、能看到图片地址，但图片裂开，优先检查上传目录的权限，尤其是缩略图生成时需要的临时目录。可以用stat -c '%a %U %G' /data/www/shopxo/public/static/upload这类命令查看具体权限，逐步缩小范围。
5.3 性能上的两个务实调优点
第一个是打开 PHP OPcache。源码是 PHP 写的，每次请求都要重新解析所有文件，不开缓存的话 CPU 会白白烧掉一大截。生产环境通常在php.ini里这样配：
opcache.enable=1 opcache.memory_consumption=128 opcache.max_accelerated_files=10000 opcache.revalidate_freq=60改完记得重启 PHP-FPM，必须看到opcache.enable => On才算生效。第二个是关闭调试模式。开发时把调试开着一路畅通，生产环境开着会把数据库 SQL、服务器绝对路径全部暴露给访问者。在应用配置里关闭调试、把错误信息改为不向页面输出即可。这两项做完，再用php -i | grep opcache确认运行参数，一套源码商城上线前的常规收尾就算结束了。
本文还有配套的精品资源，点击获取
