Swift Web 介绍

Swift Web 生态

@swift-web/cli        命令行脚手架（发布在私有 npm）
  └─ sw create / add / config / info / upgrade / run

@swift-web/framework  核心框架模块（发布在私有 npm）
  └─ 组件 / Composable / Store / 插件 / 中间件 / 模块选项

@swift-web/starter    项目工程模板（发布在私有 npm，仅供 cli 拉取，业务方不直接装）
  └─ sw create 时用 `npm pack @swift-web/starter` 拉最新版本

@swift-web/standards  生态规范单一事实源（发布在私有 npm）
  └─ 开发规范 rules / ESLint / Prettier / Stylelint 可分发配置 / commit-msg 校验

pnpm add -g @swift-web/cli
sw create YC001-WEB-我的项目
sw add page product-detail
sw upgrade

// 登录与鉴权
useLoginCheck() // 检查登录态，未登录跳转
useLoginBy() // 多方式登录（手机号/账号密码等）
useLoginDialog() // 弹出登录对话框
useAuthReady() // 等待登录流程结束（device + 凭证尝试都跑过）

// UI 交互
useModal() // 命令式弹窗
useToast() // 消息提示（成功/错误/警告）

// 媒体 / 上传 / 解密
useUploader() // 文件分片上传
useDecryptedAsset() // 加密资源（.bnc）解密 + IndexedDB 缓存

// 主题
useTheme() // 主题管理（mode 感知：resolvedTheme + toggle/system/dark/light；无条件注册）

// SEO
useSeo() // 统一 SEO 入口（og / canonical / JSON-LD / robots）

// 埋点与广告
useTracker() // 集团 WebSDK 统一埋点（track 自定义事件）
useAdTrack() // 广告曝光 / 点击埋点字段自动组装
useAdFrequency() // 广告展示频率控制（加密缓存）
useExposure() // 通用进视口一次性曝光检测（内容卡片曝光埋点 / 自有 SDK 逃生舱）

// PWA
useAddToHomescreen() // 添加到主屏（A2HS）能力探测与触发

// 交互 / 导航
useHoverPreview() // 卡片 hover 放大浮层预览的机制层（意图判定 + 定位纯函数）
useExternalRedirect() // 外链中转页：白名单校验 + noindex + 倒计时跳转
useVideoPlayerPrefs() // 播放器偏好：跳过片头片尾 / 自动播放下一集

useUserStore() // 用户信息（登录态、token、用户资料）
useSystemStore() // 系统信息（服务端注入的全局配置）

swiftConfig: {
  theme: { mode: 'toggle' },                          // 主题模式（system/toggle/dark/light）
  i18n: { enabled: true, defaultLocale: 'zh-CN' },   // 多语言
  pwa: true,                                          // PWA
  auth: {                                             // 路由守卫 + client auth init
    guardedPaths: ['/mine'],
    guestPaths: ['/login', '/register'],
  },
  obfuscate: true,                                    // JS 混淆（生产默认开启）
  websocket: true,                                    // WebSocket 客户端
  errorHandler: { enabled: true, endpoint: '/_error-report' },  // 全局错误监控
  styles: { reset: true, responsive: true },          // CSS 基础层注入开关
  systemInfo: true,                                   // /system/info 拉取（false / 对象 可选）
  suppressConsole: true,                              // 生产环境禁用 console
  image: { provider: 'noop' },                        // SwImage provider 路由
  manualChunks: {},                                   // Vite 自定义分包
  request: { timeout: 20_000 },                       // $request 全局超时 / 全局 headers
  seo: {                                              // SEO 套件（永久启用）
    aiBotPolicy: 'allow',                             // AI 训练爬虫策略（'allow' | 'disallow'）
    sitemap: { exclude: ['/preview/**'] },            // sitemap 追加排除路径（私有路径已默认排除）
  },
  tracker: true,                                      // 集团统一埋点底座（配置缺失自动降级静默）
}

项目目录/
├── app/
│   ├── components/      业务组件（PascalCase 命名）
│   ├── pages/           路由页面（kebab-case 命名）
│   ├── layouts/         布局文件（全小写命名）
│   ├── composables/     业务级 composable
│   ├── store/           业务级 Pinia store
│   ├── api/             API 模块（按功能分文件）
│   ├── assets/          CSS 变量、全局样式
│   └── plugins/         业务级插件
├── public/
│   └── images/          图片源文件（jpg/png/webp/svg）
├── i18n/                多语言翻译文件（zh-CN/zh-TW/en）
├── server/              Nitro 服务端 API
├── .env                 本地环境变量（不提交 git）
├── nuxt.config.ts       Nuxt 配置（含框架模块选项）
└── swift.config.json    Swift Web 项目元数据

┌─────────────────────────────────────────┐
│           业务层（starter）              │
│   app/pages → app/components → app/api │
│              ↓ 使用（自动导入）          │
├─────────────────────────────────────────┤
│          框架层（framework）             │
│   Sw* 组件 / use* composable / store   │
│      不得反向引用业务层内容              │
└─────────────────────────────────────────┘