开发配置文档

1. 安装 Node.js

本项目主框架为 Nuxt 4，对 Node 版本有明确要求（来源：依赖 nuxt@4.2.2 的 engines）。

• Node.js 版本要求：^20.19.0 || >=22.12.0
• 建议版本：20.19.x（20 LTS 系列）或 22.12.x 及以上

已安装可忽略此步骤。安装后可在终端执行 node -v 验证版本。

2. 获取并打开 PC 端源码

打开目录：Vortmall-Pc/（不要进入 __Tigshop-*__ 子工程目录）。

3. 安装项目依赖

在 Vortmall-Pc/ 目录下打开终端执行：

npm install

说明：

• 本工程根目录包含 package-lock.json，建议团队统一使用 npm 安装依赖，避免 lock 文件冲突。

4. 配置开发环境变量

本工程运行脚本会指定 dotenv 文件：

• npm run dev 会读取：.env.development
• npm run build/preview/generate 会读取：.env.production

4.1 创建 .env.development

说明：仓库默认不提交 .env* 文件，请在 Vortmall-Pc/ 根目录手动创建 .env.development。

1. 新建文件 .env.development（Windows 可直接用编辑器创建；也可用 PowerShell）：

# PowerShell（在 Vortmall-Pc 根目录执行）
New-Item -Path ".env.development" -ItemType File -Force | Out-Null

2. 将下方模板内容粘贴到 .env.development，并按实际环境修改：

• VITE_API_URL：后端服务地址（例如 http://localhost:8080）
• VITE_API_PREFIX：API 前缀（默认 /api）
• VITE_PROXY：是否启用 Nitro 代理（1 启用，0 关闭）
• VITE_SSR：是否启用 SSR（1 启用，0 关闭）
• VITE_APP_BASE_URL：部署子路径（如部署到 /mall/，则填 /mall/；默认 /）

开发环境模板（可直接复制）：

VITE_API_URL=http://localhost:8080
VITE_API_PREFIX=/api
VITE_PROXY=0
VITE_SSR=0
VITE_APP_BASE_URL=/

4.2 关于 VITE_PROXY（可选）

项目 nuxt.config.ts 中配置了 Nitro 的转发规则：当 VITE_PROXY=1 时，会把本机 /:5173/api/** 转发到 VITE_API_URL/api/**。

• 如果你希望通过 同源 /api/** 来避免 CORS（例如请求地址形如 http://localhost:5173/api/...），可以考虑开启 VITE_PROXY=1
• 如果项目直接请求 VITE_API_URL + VITE_API_PREFIX（形如 http://localhost:8080/api/...），通常 不需要 开启代理（但需后端允许 CORS）

5. 启动项目

在 Vortmall-Pc/ 根目录执行：

npm run dev

开发服务器固定端口（见 nuxt.config.ts）：

• Host：0.0.0.0
• Port：5173

编译成功后，终端会输出 Local / Network 访问地址，复制任一地址在浏览器打开即可（通常为 http://localhost:5173/）。

启动成功输出示例：

Local:    http://0.0.0.0:5173/
Network:  http://192.168.5.191:5173/

6. 常见问题（排障速查）

6.1 安装依赖失败 / Node 版本不兼容

• 检查 node -v 是否满足：^20.19.0 || >=22.12.0
• 清理后重装（可选）：

rm -rf node_modules
npm install

（Windows 可在资源管理器删除 node_modules 后再执行 npm install）

6.2 端口被占用

• 默认端口为 5173，如果被占用，请先释放端口后再启动

6.3 接口请求失败（401/跨域/404）

• 确认 .env.development 中 VITE_API_URL、VITE_API_PREFIX 配置正确
• 如果后端不支持 CORS，可尝试开启 VITE_PROXY=1 并确保前端请求路径走 /api/**