开发文档

〇、快速开始

上传 zip → 解压到站点根 → 配置伪静态 → 访问 /install.php → 跟着 6 步向导走 → 完成（向导成功后会自动删除 install.php）。

最容易踩的两个坑：① 伪静态必须配；② 站点根目录不要多套一层文件夹。这两件任一做错，站点都能打开，但样式和图片全丢（页面状态码看起来还是正常的）。

一、环境要求

必须满足（不满足装不下去）

• PHP 7.4 或更高（推荐 7.4 / 8.0 / 8.1）；
• 扩展：PDO、pdo_mysql、mbstring、json；
• 函数：session_start()、password_hash()、hash() 未被禁用；
• 可写目录：config/、storage/、storage/logs/。

推荐满足（缺了会功能受限）

• curl、openssl：支付对接、远程请求；
• gd：图片水印 / 缩略图 / 二次编码；
• zip：后台上传安装插件 / 主题；
• 可写目录：storage/cache/、storage/uploads/、public/uploads/、themes/、plugins/。

安装向导第 2、3 步会逐项自动检测，不满足会标红并阻止继续。

二、安装步骤

1. 上传安装包并解压到站点根目录（如 /www/wwwroot/vshop/，让 index.php 直接在站点根）；
2. 建好数据库（utf8mb4，前缀默认 vshop_）；
3. 配置伪静态：try_files $uri $uri/ /index.php?$query_string;；
4. 浏览器访问 http://你的域名/install.php，按 6 步向导填写库信息与管理员账号；
5. 完成后确认 install.php 已被删除（没删请手动删）；
6. 后台入口 /admin/login，前台会员入口 /login。

三、安装后必做

• 计划任务（否则订单不会自动过期/确认）：把这些脚本加入 crontab —— cron/order_expire.php（订单超时，建议每分钟）、cron/order_auto_confirm.php（自动确认）、cron/low_stock_alert.php（库存预警）、cron/baidu_push.php（SEO 推送，可选）；
• 支付：后台「支付设置」填易支付参数（plugins/epay 插件提供的通道），回调地址用正式 HTTPS 域名；
• 主题：默认主题 themes/default，手机端 themes/default-mobile；后台「装修」可可视化编辑（vshop_diy_blocks）；
• 微信：小程序源码在 miniprogram/，用微信开发者工具打开，改 app.js 里的接口域名后上传。

四、常见问题

• 样式/图片全丢但页面 200：伪静态没配，或站点根多套了一层目录；
• install.php 打不开：被 Web 服务器拦了（部分环境会 deny 安装文件），临时放行或换 /install；
• 插件/主题装不上：PHP zip 扩展没开，或 plugins/ / themes/ 不可写；
• 卡密发货异常：检查商品卡密池（后台商品管理里导入），以及订单状态机对应的 cron 是否在跑。

五、升级

站点根 xj_panel.php 支持「验证授权 / 在线更新」；升级请先备份 config/app.php、plugins/、themes/ 与自己的改动。