@ipzero/seaart-cli NPM

@ipzero/seaart-cli

🎨 SeaArt React Native 项目脚手架工具

🚀 一个专为海艺团队打造的企业级 React Native 开发脚手架，让团队快速构建高质量移动应用！

⭐ 特色亮点

✅ 最新技术栈 - React Native 0.76.9 + TypeScript 5.8.3 + Expo 52
✅ 企业级架构 - 完整的导航、网络、状态管理解决方案
✅ 开箱即用 - 智能缓存、请求重试、错误处理一应俱全
✅ 现代化样式 - TailwindCSS (twrnc) 集成，快速开发响应式界面
✅ 完整示例 - 从登录到列表，覆盖常见业务场景
✅ 开发友好 - 详细文档、代码模板、性能监控

📦 安装

# 全局安装（推荐）
npm install -g @ipzero/seaart-cli

# 或使用 yarn
yarn global add @ipzero/seaart-cli

# 或使用 pnpm
pnpm add -g @ipzero/seaart-cli

# 临时使用（无需安装）
npx @ipzero/seaart-cli create MyAwesomeApp

🚀 快速开始

创建新项目

# 创建标准项目
seaart create MyAwesomeApp

# 指定包名
seaart create MyAwesomeApp --package-name com.company.myapp

# 跳过依赖安装
seaart create MyAwesomeApp --skip-install

# 指定包管理器
seaart create MyAwesomeApp --package-manager yarn

项目创建过程

脚手架会自动执行以下步骤： 1. 📦 从 Git 仓库下载最新企业级模版 2. ⚙️ 配置项目名称和包名 3. 📚 安装项目依赖（可跳过） 4. 🔧 初始化 Git 仓库 5. ✅ 完成项目创建

快速开始开发

# 进入项目目录
cd MyAwesomeApp

# 安装依赖（如果之前跳过了）
pnpm install

# 启动开发服务器
pnpm start

# 运行 Android 应用
pnpm run android

# 运行 iOS 应用
pnpm run ios

# 清理缓存重新启动
pnpm start --reset-cache

🏗️ 企业级架构特性

🌐 智能网络库

import { get, post, upload } from '@/utils/http/request'

// 带缓存的 GET 请求
const userData = await get('/api/user', params, {
  cache: { ttl: 5 * 60 * 1000 }, // 5分钟缓存
  retry: { retries: 2 }, // 自动重试
  deduplication: true, // 请求去重
})

// 文件上传进度
await upload('/api/upload', file, {
  onProgress: (progress) => console.log(`${progress}%`),
})

🎨 TailwindCSS 样式系统

import { tw } from '@/utils/twcss/twrnc'

// 快速样式开发
<View style={tw('flex-1 bg-gray-100 p-4')}>
  <Text style={tw('text-xl font-bold text-blue-600 text-center')}>
    TailwindCSS 让样式开发飞起来！
  </Text>
</View>

🧭 类型安全导航

import { navigate, goBack } from '@/navigation'

// TypeScript 类型安全导航
navigate('UserProfile', { userId: '123' })
goBack()

📋 高性能列表

import { FlashList } from '@shopify/flash-list'

<FlashList
  data={posts}
  renderItem={({ item }) => <PostCard post={item} />}
  estimatedItemSize={200}
  // 自动虚拟化，性能优异
/>

📋 完整命令列表

项目创建和配置

seaart create <project-name> - 创建新的 React Native 项目
seaart setup - 配置现有项目的名称和包名
seaart doctor - 检查开发环境和项目配置
seaart info - 显示项目和环境信息

代码生成（计划中）

seaart add <type> - 添加组件、页面或功能到项目
seaart generate <generator> - 使用代码生成器快速创建代码
seaart upgrade - 升级项目到最新版本

🛠️ 支持的模板

目前提供一个企业级标准模板：

模板名称	描述	特性
`default`	海艺企业级 React Native 模板	完整导航、网络库、状态管理、样式系统、开发工具

模板特性详解

🏗️ 核心架构

React Navigation 7 + TypeScript 类型安全导航
优化版 Axios + 智能缓存 + 自动重试
TailwindCSS (twrnc) + 响应式设计
Zustand 状态管理 + 持久化
Expo Image + 缓存优化
FlashList + 虚拟化高性能列表

📱 内置组件

统一导航栏组件
通用 UI 组件库 (Button, Input 等)
高阶组件 (HOC) 封装
错误边界组件
优化图片组件

🌐 网络功能

智能缓存系统 (LRU + TTL)
请求重试机制 (指数退避)
请求去重防抖
性能监控统计
Token 自动管理
错误分类处理

🎨 开发工具

TypeScript 完整支持
ESLint + Prettier 代码规范
多语言国际化 (i18next)
主题系统配置
自定义 Hooks 库

注意: 模板从 yaoz0816/react-native-seaart-template 仓库动态下载，确保始终使用最新版本。

⚙️ 配置选项

创建项目选项

选项	类型	默认值	描述
`--template`	string	`default`	使用的项目模板
`--package-name`	string	`com.seaart.{projectname}`	应用包名
`--package-manager`	string	`pnpm`	包管理器 (npm/yarn/pnpm)
`--typescript`	boolean	`true`	启用 TypeScript
`--git`	boolean	`true`	初始化 Git 仓库
`--no-git`	boolean	`false`	不初始化 Git 仓库
`--skip-install`	boolean	`false`	跳过依赖安装

环境要求

Node.js: ≥18.0.0
pnpm: ≥8.0.0 （推荐）
React Native CLI: 最新版
Android Studio: 最新版
Xcode: 最新版 (仅 macOS)
Git: 用于下载模版和版本控制

🎨 项目目录结构

创建的项目包含以下完整目录结构：

📱 MyAwesomeApp/
├── 🔧 配置文件
│   ├── app.json              # Expo 配置
│   ├── babel.config.js       # Babel 配置
│   ├── metro.config.js       # Metro 打包配置
│   ├── tsconfig.json         # TypeScript 配置
│   └── seaart-config.json    # 项目自定义配置
├── 📱 平台文件
│   ├── android/              # Android 原生代码
│   ├── ios/                  # iOS 原生代码
│   └── index.js             # 应用入口文件
├── 📂 源代码
│   ├── src/
│   │   ├── components/       # 通用组件
│   │   │   ├── common/      # 公共组件
│   │   │   ├── ui/          # UI 组件库
│   │   │   └── hoc/         # 高阶组件
│   │   ├── screens/         # 页面组件
│   │   ├── navigation/      # 导航配置
│   │   ├── stores/          # 状态管理 (Zustand)
│   │   ├── utils/           # 工具函数
│   │   ├── types/           # TypeScript 类型定义
│   │   ├── api/             # API 接口定义
│   │   ├── hooks/           # 自定义 Hooks
│   │   ├── locales/         # 国际化文件
│   │   ├── theme/           # 主题配置
│   │   ├── config/          # 应用配置
│   │   └── assets/          # 静态资源
├── 🛠️ 开发工具
│   ├── .eslintrc.js         # ESLint 配置
│   ├── .prettierrc.js       # Prettier 配置
│   ├── jest.config.js       # Jest 测试配置
│   └── scripts/             # 构建脚本
└── 📚 文档
    ├── README.md            # 项目说明
    ├── GETTING_STARTED.md   # 新人上手指南
    └── QUICK_REFERENCE.md   # 快速参考手册

🚀 项目内置脚本

创建项目后，您可以使用以下脚本：

# 开发相关
pnpm start                    # 启动 Metro 服务器
pnpm run android             # 运行 Android 应用
pnpm run ios                 # 运行 iOS 应用

# 代码质量
pnpm run lint                # 代码检查
pnpm run lint:fix            # 自动修复代码问题
pnpm run format              # 格式化代码
pnpm test                    # 运行测试

# 清理缓存
pnpm start --reset-cache     # 重置 Metro 缓存
pnpm run clean:android       # 清理 Android 缓存
pnpm run clean:ios           # 清理 iOS 缓存

# 项目配置
pnpm run setup               # 修改应用名称和包名
pnpm run updateI18n          # 更新国际化文件

# 构建分析
pnpm run bundle:visualizer:android  # Android 包分析
pnpm run bundle:visualizer:ios      # iOS 包分析

🔧 故障排除

常见问题解决方案

模版下载失败

# 检查网络连接和 Git 访问权限
git clone https://github.com/yaoz0816/react-native-seaart-template.git

依赖安装失败

# 清理缓存后重新安装
pnpm store prune
rm -rf node_modules
pnpm install

Metro 缓存问题

# 重置 Metro 缓存
pnpm start --reset-cache

Android 构建失败

# 清理 Android 缓存
cd android && ./gradlew clean
cd .. && pnpm run android

iOS 构建失败

# 清理 iOS 缓存和重新安装 Pods
pnpm run clean:ios

获取帮助

📖 查看命令帮助: seaart --help
🔍 检查环境: seaart doctor
🐛 问题反馈: GitHub Issues
📚 项目文档: 查看生成项目中的 GETTING_STARTED.md

📊 版本更新

# 检查当前版本
seaart --version

# 更新到最新版本
pnpm update -g @ipzero/seaart-cli

# 查看更新日志
npm info @ipzero/seaart-cli

🎯 使用示例

企业级项目创建

# 创建企业级项目
seaart create SeaArtMobile \
  --package-name com.seaart.mobile \
  --package-manager pnpm

# 进入项目并启动开发
cd SeaArtMobile
pnpm install
pnpm start

# 在另一个终端运行应用
pnpm run android  # 或 pnpm run ios

快速体验功能

创建项目后，您可以立即体验以下功能：

🧭 导航系统 - 查看 src/navigation/ 目录
🌐 网络请求 - 查看 src/utils/http/ 目录和示例
🎨 样式系统 - 查看 src/theme/ 和 TailwindCSS 配置
📋 高性能列表 - 体验 FlashList 组件
🔄 状态管理 - 查看 src/stores/ 目录
🌍 国际化 - 查看 src/locales/ 多语言支持

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

Fork 项目仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

开发环境设置

# 克隆仓库
git clone https://github.com/yaoz0816/seaart-cli.git
cd seaart-cli

# 安装依赖
pnpm install

# 开发模式
pnpm run dev

# 构建项目
pnpm run build

# 运行测试
pnpm test

# 本地测试 CLI
node bin/seaart create TestApp