ECShopX Admin 开发文档

项目简介

ECShopX Admin 是一个基于 Vue.js 2.x 的电商管理后台系统，支持多平台部署，采用微前端架构，具备完整的商城管理功能。

Node 环境要求

16.16.0 (固定版本，在 package.json 中指定)

npm 或 yarn

nvm 管理 Node.js 版本

# 使用 nvm 安装指定版本
nvm install 16.16.0
nvm use 16.16.0

安装步骤

1. 安装依赖

# 设置 npm 镜像源
npm config set registry https://registry.npmmirror.com
npm config set @shopex:registry http://registry.npm.ishopex.cn

# 查看是否设置成功
npm config get registry

# 安装依赖
npm install

# 安装私有包
npm i @shopex/finder –registry=http://registry.npm.ishopex.cn

# finder文档
https://shopex.yuque.com/vi1gbe/sqmvgo/c11cd11b903d54c6cc71f215537d4b3d

2. 配置环境变量

项目使用环境变量进行配置，需要根据实际情况创建 .env 文件。

运行项目

1. 开发环境

# 运行项目
npm run dev:yd

开发服务器配置：

端口：8080

热更新：已启用

自动打开浏览器：已启用

Gzip 压缩：已启用

2. 生产环境构建

# 构建生产版本
npm run build:yd

3. 代码质量工具

# 代码格式化和检查
npm run lint           # ESLint 检查和修复
npm run prettier       # Prettier 格式化
npm run commit         # 规范化提交信息

# Git Hooks 设置
npm run husky          # 安装 husky
npm run husky:add      # 添加 pre-commit 和 commit-msg hooks

项目目录结构

ecshopx-admin/
    ├── build/                    # 构建工具
├── docs/                     # 项目文档
│   ├── cheatsheet/          # 组件使用说明
│   └── prd/                 # 产品需求文档
├── public/                   # 静态资源
├── src/                      # 源代码
│   ├── api/                 # API接口定义（请求封装、接口地址管理）
│   ├── assets/              # 静态资源
│   │   ├── images/         # 图片资源
│   │   ├── fonts/          # 字体文件
│   │   └── svgs/           # SVG 图标
│   ├── bootstrap/           # 应用启动配置
│   ├── common/              # 公共数据
│   ├── components/          # 公共组件库
│   │   ├── sp-*/           # 自定义组件（以 sp- 前缀）
│   │   ├── function/       # 功能性组件
│   │   └── template/       # 模板组件
│   ├── composables/         # Vue 组合式 API
│   ├── config/              # 配置文件
│   │   └── products/       # 各平台配置
│   ├── consts/              # 常量定义
│   ├── directives/          # 自定义指令
│   ├── filters/             # 过滤器
│   ├── i18n/               # 国际化
│   ├── layout/             # 布局组件
│   ├── mixins/             # 混入
│   ├── router/             # 路由配置
│   ├── store/              # Vuex 状态管理
│   ├── styles/             # 样式文件
│   ├── utils/              # 工具函数
│   ├── view/               # 业务页面
│   │   ├── auth/           # 权限管理
│   │   ├── base/           # 基础设置
│   │   ├── goods/          # 商品管理
│   │   ├── mall/           # 商城管理
│   │   ├── marketing/      # 营销管理
│   │   ├── member/         # 会员管理
│   │   ├── order/          # 订单管理
│   │   └── wxapp/          # 小程序管理
│   └── views/              # 通用视图组件
├── newpc_b2c/              # B2C 微前端资源
├── newpc_bbc/              # BBC 微前端资源
├── package.json            # 项目配置
├── vue.config.js           # Vue CLI 配置
├── Dockerfile              # Docker 构建文件
├── Docker-Atlas            # Atlas 部署文件
└── tailwind.config.js      # Tailwind CSS 配置

核心组件说明

1. 表单组件系列

  • 增强型表单组件，支持动态表单配置
  • 筛选表单组件，用于列表页面筛选
  • 增强型输入框组件

2. 选择器组件系列

  • 通用选择器组件，支持多种选择类型
  • 图片选择器，支持上传和选择
  • 视频选择器
  • 地区选择器
  • 店铺选择器
  • 商户选择器

3. 展示组件系列

  • 商品卡片组件
  • 商品组合展示
  • 图片展示组件
  • 价格展示组件
  • 图标组件

4. 布局组件系列

  • 页面容器组件
  • 页面头部组件
  • 内容卡片组件
  • 标签页组件
  • 抽屉组件
  • 对话框组件

5. 功能组件系列

  • 剪贴板功能
  • 倒计时组件
  • 分页组件
  • 拖拽组件

6. 业务组件

  • 商品选择器
  • 店铺选择
  • 模板预览

7、spIcon说明

https://iconpark.oceanengine.com/official



环境变量说明

项目使用以 VUE_APP_ 前缀的环境变量进行配置：

1. 基础配置

  • 项目名称
  • 是否为 SaaS 模式，默认 false
  • API 请求地址，默认 /api
  • 静态资源公共路径，默认 /
  • 微信图片服务地址
  • 微信授权回调地址
  • 路径前缀配置
  • 乾坤微前端入口路径，默认 /newpc/
  • 是否启用 OSS CDN 上传
  • 免费版本标识
  • 地图key
  • 初值配置标识
  • 有道翻译 APP ID（开发环境）
  • 有道翻译 APP Key（开发环境）
  • 本地配送驱动 默认 dada

部署方式

1. 传统部署(构建静态资源)

# 构建项目(dist/ 目录)
npm run build:yd

2. Docker部署

？？？？？

常见问题

1. 依赖安装问题

如果遇到依赖安装失败，尝试：

# 清除缓存
npm cache clean –force
rm -rf node_modules package-lock.json

# 重新安装
npm install

2. 构建问题

如果构建失败，检查：

3. 开发服务器问题

如果开发服务器启动失败：

检查端口 8080 是否被占用

确认环境变量配置正确

查看控制台错误信息