02 - 快速开始
环境准备
Node 版本
项目要求 Node.js 16.16.0（见 package.json 的 engines 字段和 Dockerfile 基础镜像）。
# 推荐使用 nvm 管理
nvm install 16.16.0
nvm use 16.16.0
# 验证
node -v # 应输出 v16.16.0其他依赖
- npm（随 Node 安装）
- 微信开发者工具（微信小程序调试用）
- Chrome/Edge（H5 调试用）
安装
# 克隆代码后
cd ecshopx-vshop
# 安装依赖（配置了 npmmirror + shopex 私有 registry）
npm ci
npm ci严格按照package-lock.json安装，确保版本一致。首次安装或无 lock 文件时使用npm install。
npm registry 配置
项目 .npmrc 配置了：
- 淘宝镜像
registry.npmmirror.com加速公共包 - shopex 私有 registry
reg.ishopex.cn获取内部包
环境变量配置
.env 文件结构
项目根目录有 .env（默认模板）和 .env.local（本地覆盖，不提交 Git）。
.env 定义了所有需要的环境变量名（值为空，等待覆盖）：
APP_BASE_URL= # 后端 API 地址
APP_WEBSOCKET= # WebSocket 地址
APP_COMPANY_ID= # 企业/租户 ID
APP_PLATFORM= # 产品版本 (standard/platform)
APP_CUSTOM_SERVER= # 自定义 H5 服务地址
APP_HOME_PAGE= # 首页路径
APP_TRACK= # 埋点类型
APP_ID= # 微信小程序 AppID
APP_MAP_KEY= # 地图 Key
APP_MAP_NAME= # 地图名称
APP_IMAGE_CDN= # 图片 CDN
APP_DIANWU_URL= # 店务端 URL
APP_MERCHANT_URL= # 商家入驻 URL
APP_ADAPAY= # Adapay 支付开关
APP_LIVE= # 直播开关
APP_DEFAULT_LANGUAGE= # 默认语言本地开发配置
复制 .env 为 .env.local，填入实际值：
cp .env .env.local编辑 .env.local：
APP_BASE_URL=https://your-api.example.com
APP_WEBSOCKET=wss://your-api.example.com/ws
APP_COMPANY_ID=38
APP_PLATFORM=standard
APP_ID=wx1234567890abcdef
APP_MAP_KEY=YOUR_MAP_KEY
APP_DEFAULT_LANGUAGE=zhcn
.env.local不提交 Git，仅本地使用。
多客户配置
scripts/run.sh 提供交互式多客户构建：
# 交互式选择客户
bash scripts/run.sh
# 直接指定参数
bash scripts/run.sh "wxappid" "https://api.example.com" "AppName" ...客户配置存储在 scripts/companys.conf，按 [section] 分区块，每个客户一个配置。
本地调试
微信小程序调试
# 启动微信小程序开发模式（watch）
npm run dev:weapp构建产物输出到 dist/weapp/，用微信开发者工具打开该目录即可调试。
关键配置项：
- AppID：使用
.env.local中的APP_ID，或微信开发者工具中切换 - ext 配置：微信通过 ext.json 注入
company_id等参数，见src/utils/index.js中的getExtConfigData()
H5 调试
# 启动 H5 开发服务器
npm run dev:h5H5 dev server 默认运行在 http://localhost:10086（Taro 默认端口）。
company_id 自动提取：H5 环境下，req.js 会从域名自动提取 company_id（如 m38.shopex123.com → 38）。本地调试用 localhost 时需要手动设置。
i18n 调试模式
# 微信小程序 + i18n
npm run dev:weapp:i18n
# H5 + i18n
npm run dev:h5:i18ni18n 模式下，非默认语言包通过分包异步加载，便于调试多语言。
构建命令
完整构建命令列表
| 命令 | 说明 |
|---|---|
npm run build:weapp | 构建微信小程序 |
npm run build:weapp:live | 构建微信小程序（带直播） |
npm run build:h5 | 构建 H5 |
npm run dev:weapp | 微信小程序 watch 模式 |
npm run dev:h5 | H5 watch 模式 |
npm run dev:weapp:i18n | 微信小程序 i18n 调试模式 |
npm run dev:h5:i18n | H5 i18n 调试模式 |
npm run commit | Commitizen 交互式提交 |
本项目开发和发布只使用 weapp 与 h5 构建命令。
构建产物
| 平台 | 输出目录 |
|---|---|
| 微信小程序 | dist/weapp/ |
| H5 | dist/h5/ |
输出目录由
config/index.js的DIST_PATH = dist/${process.env.TARO_ENV}决定。
Docker 构建
标准 Docker 构建
docker build \
--build-arg CMD="npm run build:h5" \
--build-arg APP_BASE_URL="https://api.example.com" \
--build-arg APP_COMPANY_ID="38" \
--build-arg APP_PLATFORM="standard" \
--build-arg APP_ID="wx1234567890" \
...
-t ecshopx-vshop:h5 .Dockerfile 是多阶段构建：
- Builder 阶段：Node 16 + Python3 Alpine 镜像，
npm ci+ 构建 - Runtime 阶段：
steebchen/nginx-spaNginx 镜像，部署 H5 产物
常见问题
1. npm install 失败
检查 .npmrc 配置，确保能访问 reg.ishopex.cn 私有 registry。公司网络外可能需要 VPN。
2. 微信小程序编译报错
确保使用 Node 16.16.0。更高版本的 Node 可能导致 Taro 3.6.x 兼容问题。
3. H5 调试时 company_id 不正确
本地 localhost 域名无法自动提取 company_id。在 .env.local 中显式设置 APP_COMPANY_ID。
4. 语言包未加载
确保使用 dev:*:i18n 模式调试多语言。默认 dev 模式下，非默认语言包可能不会正确加载。
5. 样式在 H5 和小程序不一致
检查 config/index.js 的 sass.resource 配置：weapp 使用 weapp-mixins.scss，h5 使用 h5-mixins.scss。确保条件编译正确。