LikeShop 二开环境搭建：本地开发、接口调试与前端联调全流程

LikeShop 二开环境搭建：本地开发、接口调试与前端联调全流程

上一篇聊了 LikeShop 的源码结构和核心业务代码定位，这篇接着讲环境搭建。说实话，LikeShop 的部署方式有好几种------Docker 一句命令、宝塔面板一键部署、PHPStudy 本地搭建------每种适合不同的场景。这篇文章把我实际用过的几种方式都梳理一遍，重点讲清楚 本地开发环境怎么配、接口怎么调、前端怎么联调，帮你在二开时少走弯路。

一、环境准备：三种部署方式怎么选

LikeShop 免费企业版 v3.5.1 对环境的要求如下：

产品线	Nginx/Apache	PHP	MySQL
单商户/多商户/外卖/回收租赁	不限制	7.2～7.4（推荐7.2）	5.7
单商户高级版/SaaS版	不限制	8.0	5.7

官方建议使用推荐版本以减少兼容性问题-1。

三种部署方式各有适用场景：

• Docker 一句命令：适合快速体验，几分钟就能跑起来，但不建议用于生产环境

• 宝塔面板一键部署：适合服务器上线，也适合本地虚拟机做集成测试

• PHPStudy 本地搭建：适合日常开发调试，修改代码后即时生效

如果你只是想先看看 LikeShop 长什么样，用 Docker 最快；如果要正经做二开，建议 PHPStudy 或宝塔。

Docker 快速体验

安装 Docker 后，终端运行：

docker run -d --name likeshop -p 20208:80 -e MYSQL_ROOT_PASSWORD=root registry.cn-guangzhou.aliyuncs.com/likeshop/php-b2c:latest

如果需要持久化数据，用带挂载的命令：

docker run -d --name likeshop \
  -v 主机存储数据库路径:/var/lib/mysql \
  -v 主机存储项目代码路径:/var/www/html/likeshop \
  -p 访问端口:80 \
  -e MYSQL_ROOT_PASSWORD=你的密码 \
  registry.cn-guangzhou.aliyuncs.com/likeshop/php-b2c:latest

启动后等待约1分钟，然后访问：

• 安装程序：http://127.0.0.1:20208

• PC 管理后台：http://127.0.0.1:20208/admin/login（账号 admin / 密码 123456）

• PC 前台：http://127.0.0.1:20208/pc/

• 手机端前台：http://127.0.0.1:20208/mobile/

注意 Docker 部署每次会下载最新源码，数据默认账号密码都是 root。不熟悉 Docker 的话不要用于生产环境，可能造成数据丢失。

二、服务端本地搭建（PHPStudy 方案）

这是日常二开最常用的方式。

1. 环境安装

下载安装 PHPStudy（https://www.xp.cn/download.html），然后在软件管理中安装 PHP 7.2、Nginx、MySQL 5.7。

2. 源码部署

从 Gitee 或 GitHub 下载源码包，只需要把 server 文件夹部署到网站根目录，其他文件夹（admin、uniapp、pc）是前后端分离的前端源码，本地开发时不需要上传到 Web 服务器-。

将 server 文件夹复制到 PHPStudy 的 WWW 目录下解压。注意：很多人解压后重新打包会遗漏隐藏文件，导致无法安装 ，官方部署文档特别提醒了这一点-1。

3. 创建站点与伪静态

在 PHPStudy 中创建网站，运行目录设置为 public，伪静态规则选择 ThinkPHP，或者手动填入：

location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=/$1 last;
    }
}

这个伪静态规则是 LikeShop 的标准配置-28。

4. 访问安装程序

浏览器访问站点域名，进入在线安装界面。环境监测通过后，填写数据库信息和管理员账号密码即可完成安装。如果提示需要在 MySQL 配置文件修改 sql-mode，按以下配置添加并重启 MySQL：

sql-mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

这一步的坑主要出在 PHP 扩展上。LikeShop 需要 fileinfo 等扩展，如果环境监测不通过，在 PHPStudy 的 PHP 设置里安装对应的扩展即可-1。

5. 关闭移动端调试图标

本地开发时移动端右下角会显示调试图标，如果不需要，在项目根目录的 .env 文件中把对应值改成 false 即可-5。

三、管理后台前端本地开发

管理后台源码在 admin 或 web 目录下（不同版本命名可能不同）。

1. 环境变量配置

找到根目录下的 .env.development.example 文件，复制一份去掉 .example 后缀，修改其中的接口地址为本地部署的服务端地址：

VITE_APP_BASE_URL='http://你的本地域名'

保存后，将文件名改为 .env.development-。

2. 安装依赖与启动

bash

cd admin
npm install
npm run serve

启动后在浏览器访问终端返回的地址即可。如果修改了服务端接口，管理后台会自动热更新，开发效率很高-。

四、移动端 uni-app 本地开发

移动端源码在 uniapp 目录下，使用 HBuilderX 进行开发和编译。

1. 编辑器准备

下载 HBuilderX App 开发版 （不是标准版），然后安装 scss/sass 编译插件 ，插件地址：https://ext.dcloud.net.cn/plugin?id=2046-16。

2. 环境变量配置

这是最容易卡住的一步。打开 uniapp 目录，找到 .env.development.example 文件：

• 创建副本，去掉 .example 后缀

• 修改其中的域名地址为本地服务端部署的域名

注意：官方文档特别强调不要使用本地地址（localhost），必须用部署好的域名 。因为 uni-app 的条件编译在多端运行时，localhost 在不同环境下的解析不一致-16。

同理，.env.production.example 为生产环境配置，正式发布时一定要配置 HTTPS。

3. 运行项目

用 HBuilderX 打开 uniapp 目录，在菜单栏选择「运行」→「运行到浏览器」或「运行到小程序模拟器」。

如果编译时报错 "请参考官方文档在 .env 文件下配置请求域名" ，说明环境变量文件没有正确配置或保存，检查文件名是否去掉了 .example 后缀，以及域名是否填写正确-。

4. 设置 DCloud AppID

第一次使用 LikeShop 时需要重新设置 DCloud AppID。找到 main.js 文件，在 HBuilderX 中点击「重新获取」→「继续」即可完成-16。

五、接口调试实战

LikeShop 的 API 分为两套：PC 管理后台接口基础 URL 为 /adminapi，小程序/移动端接口基础 URL 为 /shopapi -35。

通用请求规范

所有接口在请求时有一些固定参数需要在 Header 中传递：

参数名	类型	说明
token	string	验证令牌，所有需要登录的接口必填
version	string	客户端版本，所有接口都需要传

列表接口的固定参数：

参数名	类型	默认值	说明
page_no	int	1	页码
page_size	int	25	每页数量
order_by	string	desc	排序方式
field	string	---	排序字段名称

返回值通用格式为：

json
{
  "code": 0,
  "show": 0,
  "msg": "",
  "data": {}
}

其中 code 字段：1=操作成功，0=操作失败，-1=需要重新登录，2=打开新页面-35。

Postman 调试示例

以获取订单列表为例：

GET /adminapi/order.order/lists
Headers:
  token: 你的登录令牌
  version: 1.0.0
Query Params:
  page_no: 1
  page_size: 10

一个容易忽略的坑

列表分页参数虽然前端传的是 page_no 和 page_size，但 LikeShop 的导出功能底层依赖 limit() 方法，不能用 ThinkPHP 的 page() 。如果你在二开时自定义了列表查询，记得用 limit() 而不是 page()，否则导出功能会报错。

六、前后端联调与跨域处理

前后端分离项目联调时，跨域是最常见的问题。LikeShop 的跨域处理主要有以下几个层面：

1. 服务端跨域配置

LikeShop 在中间件中处理跨域请求，核心文件是：

server/app/common/http/middleware/LikeAdminAllowMiddleware.php

如果联调时遇到跨域被拦截，可以检查这个中间件的配置。官方文档也提到，如果遇到跨域相关问题，可以临时关闭服务器本站点的跨域攻击设置并重启 Nginx 和 PHP-45。

2. 前端代理配置

在本地开发时，更推荐用前端代理解决跨域，而不是修改服务端配置。管理后台（Vue/Vite 项目）可以在 vite.config.js 中配置：

server: {
  proxy: {
    '/adminapi': {
      target: 'http://你的服务端域名',
      changeOrigin: true
    },
    '/shopapi': {
      target: 'http://你的服务端域名',
      changeOrigin: true
    }
  }
}

这样前端请求 /adminapi/xxx 会被代理到服务端，跨域问题就绕过了。

3. 联调检查清单

• 服务端能正常返回接口数据（先用 Postman 验证）

• 前端 .env 文件中配置的服务端地址正确

• 登录接口返回的 token 是否正确存储在 localStorage 或 Vuex 中

• 后续请求的 Header 中是否携带了 token

七、二开环境搭建的效率优化

环境跑通之后，还有几件事可以提升日常开发效率：

用 Git 管理二开代码。 LikeShop 官方会持续更新源码，如果不做版本管理，后续同步官方更新时很难处理冲突。建议以官方源码为上游仓库，自己的改动在独立分支上开发。

配置 Xdebug 调试。 PHP 项目调试全靠 var_dump 太原始了。在 PHPStudy 的 PHP 设置中开启 Xdebug，配合 PhpStorm 或 VS Code 的调试插件，可以在 OrderLogic 中打断点逐步追踪订单创建流程。

善用 AGENTS.md 和 CLAUDE.md。 项目根目录的这两个文件对核心业务实体和数据流转做了结构化描述。用 Cursor 或 Claude Code 辅助开发时，AI 能直接读取这些文件来理解项目上下文，大幅减少你解释"这个订单逻辑在哪"的时间。

八、常见问题速查

Q：安装时提示目录权限不足？

A：将 public 目录权限设置为 777 或确保 Web 用户（www）有读写权限。

Q：管理后台登录后接口全部返回 -1？

A：token 过期或未正确传递。检查请求头中是否携带了 token，以及 token 是否在有效期内。

Q：移动端编译报错找不到请求域名？

A：检查 uniapp 目录下的 .env.development 文件是否存在、域名是否正确填写、文件是否保存。

Q：MySQL 安装时报 sql-mode 错误？

A：在 MySQL 配置文件中添加 NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION 并重启 MySQL。

Q：Docker 部署后访问 502？

A：等待约 1 分钟，Docker 首次启动会下载最新源码并初始化数据库，需要一些时间。

九、总结

LikeShop 的环境搭建不算复杂，但有几个关键点容易踩坑：PHP 版本要对、运行目录要设 public、伪静态要用 ThinkPHP 规则、前端环境变量文件要去掉 .example 后缀。把这几步做好，环境基本就能跑通。

联调阶段记住两套接口前缀：管理后台走 /adminapi，移动端走 /shopapi，Header 中带好 token 和 version，基本不会有大问题。