shield_lock
JinDaGe
Contact
← Back to skills
extension
Category: Development & EngineeringNo API key required

移动端初始化skill

基于 `Vue 3 + Vite + Vant` 创建一套偏移动端 H5 的起步项目

personAuthor: vanDarkMasterhubModelScope
downloadDownload package

Mobile Vue3 Vite Vant Scaffold

基于 Vue 3 + Vite + Vant 创建一套偏移动端 H5 的起步项目，并优先生成一套容易继续接业务的默认结构。

工作流

1. 先确认初始化选项

在创建项目之前，先确认这些参数：

  1. 项目名称
  2. 使用 TypeScript 还是 JavaScript
  3. 是否安装 echarts
  4. 是否安装高德地图包 @amap/amap-jsapi-loader
  5. 是否生成底部 tabbar
  6. 是否生成默认起步页面：
    • 登录页（手机号 + 验证码）
    • 首页
    • 用户中心页
  7. 是否立即执行依赖安装
  8. 是生成到新项目子目录，还是直接原地生成到当前目标目录
  9. 是否生成项目级 AGENTS.md 与 docs/codex-guide.md

如果用户没有特别要求，使用这些默认值：

  • 语言：JavaScript
  • 安装 axios
  • 安装 pinia
  • 不安装 echarts
  • 不安装高德地图
  • 生成 tabbar
  • 生成默认起步页面
  • 生成项目级 AGENTS.md 与 docs/codex-guide.md
  • 不自动执行依赖安装

2. 优先使用自带脚本

这个 skill 自带一个初始化脚本：

  • scripts/create-project.mjs

优先运行这个脚本来生成项目，而不是每次手写文件。

默认用法：

node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs

如果这个 skill 已安装到 Codex 全局目录，也可以直接使用全局路径运行：

node C:\Users\Admin\.codex\skills\mobile-vue3-vite-vant-scaffold\scripts\create-project.mjs

常用参数：

node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --name my-mobile-app --target D:\workspace
node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --target D:\workspace\SALEH5 --current
node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --name my-mobile-app --js --echarts --amap
node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --name my-mobile-app --no-tabbar --no-starter-pages
node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --name my-mobile-app --no-codex-files
node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --name my-mobile-app --install
node skills/mobile-vue3-vite-vant-scaffold/scripts/create-project.mjs --name my-mobile-app --install --build

如果用户已经手动创建好一个空目录，希望文件直接落在这个目录里，不要再套一层项目名目录，优先使用 --current。

3. 生成后的目录预期

默认应生成下面这类结构：

project-name/
  src/
    api/
      modules/
      request.ts|js
    layout/
      TabbarLayout.vue
    router/
      guard.ts|js
      index.ts|js
    store/
      index.ts|js
    utils/
      auth.ts|js
      storage.ts|js
      validate.ts|js
      amapLoader.ts|js   (启用高德时生成)
    views/
      login/
        loginPage.vue
      home/
        homePage.vue
      mine/
        minePage.vue
      welcome/
        welcomePage.vue  (未生成默认起步页时生成)
    App.vue
    main.ts|js
    style.css
  .env.development
  .env.build-dev
  .env.build-prod
  AGENTS.md
  docs/
    codex-guide.md
  index.html
  package.json
  vite.config.ts|js
  tsconfig.json         (TypeScript 时生成)

4. 生成规则

Request 层

统一生成：

  • src/api/request.*
  • src/api/modules/auth.*
  • src/api/modules/demo.*

要求：

  • 从 VITE_APP_BASE_API 读取 baseURL
  • 自动注入 token
  • 默认支持全局 loading
  • 统一处理请求错误
  • 401 / token 过期 时自动清理登录态并跳回登录页
  • 业务响应如果显式返回 code，则默认按 code === 200 视为成功，其它状态统一按错误处理
  • 页面层不直接写裸 axios

默认请求策略：

  • 通过并发计数控制全局 loading，避免多个请求时过早关闭
  • loading toast 需要单独持有实例并定向关闭，避免 showFailToast 刚弹出就被全局 closeToast() 误关掉
  • 支持 meta.showLoading 控制是否显示 loading
  • 支持 meta.loadingMessage 自定义 loading 文案
  • 支持 meta.silentError 控制是否静默错误提示
  • 兼容两类登录失效：HTTP 401，以及业务层返回 code/msg 表示 TOKEN失效 / 登录过期 / 重新登录

构建与二级目录部署

默认生成：

  • npm run build:dev
  • npm run build:prod

要求：

  • build:dev 使用 .env.build-dev
  • build:prod 使用 .env.build-prod
  • Vite 的 base 通过 VITE_APP_BASE_PATH 控制，适配部署到二级目录
  • 输出目录通过 VITE_APP_OUT_DIR 控制，便于区分不同环境构建产物

路由与守卫

统一生成：

  • src/router/index.*
  • src/router/guard.*
  • @ -> src 别名配置

守卫逻辑：

  • 显式维护路由白名单，默认至少包含登录页
  • 进入白名单页面时优先放行
  • 需要登录的页面，没有 token 时跳登录页
  • 已登录进入登录页时，跳首页

别名要求：

  • vite.config.* 中默认配置 @ 指向 src
  • TypeScript 模式下同时生成 tsconfig.json 的 paths
  • JavaScript 模式下同时生成 jsconfig.json
  • src 内跨目录引用时，默认必须使用 @/xxx 导入
  • 只有同目录文件之间才优先使用 ./xxx
  • 尽量不要生成 ../../api/modules/liveSale 这类层层回退的相对路径

页面默认能力

页面文件命名约定：

  • 页面目录可以按业务分组
  • 具体页面文件优先使用驼峰语义名，例如 loginPage.vue、userPayFen.vue
  • 除非用户明确要求，否则不要在业务目录里统一生成 index.vue
  • 生成的 js/ts 方法、函数和 store action，默认在方法前补一行简短中文注释，说明这个方法具体做什么，不要写成空话或过度啰嗦

Codex 协作文件

默认生成：

  • 根目录 AGENTS.md
  • docs/codex-guide.md

要求：

  • AGENTS.md 负责约束当前项目内 Codex 的默认协作规则
  • docs/codex-guide.md 负责记录这套脚手架在当前项目中的使用方式和常见协作示例
  • 如果用户明确不需要，可通过 --no-codex-files 关闭生成

如果启用了默认起步页面：

  • 登录页：手机号 + 验证码 + 获取验证码倒计时
  • 首页：常用入口区 + 项目能力提示区
  • 用户中心页：用户信息展示 + 常用操作项

如果没有启用默认起步页面：

  • 生成一个最小 welcome 页面
  • 保留基础路由、请求层、工具层和守卫文件

tabbar 规则

如果启用了 tabbar：

  • 用 TabbarLayout.vue 承载 home 和 mine
  • 使用 Vant 的 van-tabbar

如果没有启用 tabbar：

  • 直接生成扁平路由
  • home、mine 作为普通页面存在

可选依赖规则

只有在用户明确选择时才加入：

  • echarts
  • @amap/amap-jsapi-loader

如果启用了高德地图：

  • 额外生成 src/utils/amapLoader.*
  • 在 .env.* 中加入 VITE_AMAP_KEY

使用建议

适合的场景

  • 新建移动端 H5 项目
  • 想统一一套 Vue3 + Vite + Vant 目录规范
  • 想要一套开箱即用的登录/首页/我的页起步页
  • 想让 Codex / Cursor 以后可以重复执行同一种初始化流程

不适合的场景

  • 需要 uni-app / 小程序
  • 需要后台管理风格而不是移动端 H5
  • 需要 SSR / Nuxt

资源

scripts/create-project.mjs

用于交互式生成项目骨架。它会：

  • 询问初始化选项
  • 生成基础文件
  • 按选项拼装依赖和路由
  • 可选执行依赖安装
  • 可选执行构建验证

references/project-conventions.md

用于说明这套脚手架的目录、路由、请求封装和页面职责约定。需要调整默认约定时，先读这个文件。