Skip to content

README.zh-CN.md

Latest commit

 

History

History
240 lines (177 loc) · 6.19 KB

README.zh-CN.md

File metadata and controls

240 lines (177 loc) · 6.19 KB

Next.js 现代化启动模板

一个现代化、极简的 Next.js 15 启动模板，集成了 Motion 动画、Zustand 状态管理、Tailwind CSS v4 和 TypeScript。生产就绪，内置深色模式、工程化最佳实践和自动部署。

语言: 中文 | English

使用 Vercel 部署 部署到 GitHub Pages

✨ 特性

  • 🚀 Next.js 15 - 最新的 React 框架，支持 App Router 和 Turbopack
  • 🎨 Tailwind CSS v4 - 新一代原子化 CSS 框架
  • 🐻 Zustand - 轻量级、可扩展的状态管理
  • 🎭 Motion - 高性能动画库，声明式 API
  • 🌗 深色模式 - 无缝主题切换，支持系统偏好
  • 📘 TypeScript - 完整类型安全，启用严格模式
  • 🛠️ 工程化工具 - ESLint、Prettier、Husky、lint-staged 和 Commitlint
  • 🚀 GitHub Actions - 自动部署到 GitHub Pages
  • 📦 clsx - 条件类名工具，让组件代码更简洁

🎯 设计理念

这个模板提供极简、生产就绪的基础，而非臃肿的框架。它只包含必需品，让你可以：

  • 添加喜欢的 UI 组件库（shadcn/ui、Ant Design、Material-UI 等）
  • 集成任何数据库方案（Prisma、Drizzle、Supabase 等）
  • 实现身份认证（NextAuth、Clerk、Auth0 等）
  • 使用自己的后端架构进行扩展

🚀 快速开始

环境要求

  • Node.js 18+
  • pnpm（推荐）或 npm/yarn

安装

# 克隆仓库
git clone https://github.com/crper/next-modern-starter.git
cd next-modern-starter

# 安装依赖
pnpm install

# 使用 Turbopack 启动开发服务器
pnpm dev

在浏览器中打开 http://localhost:3000 查看应用。

🚀 部署

GitHub Pages（自动部署）

推送到 main 或 master 分支即可通过 GitHub Actions 自动部署：

  1. 在仓库设置中启用 GitHub Pages
  2. 将源设置为 "GitHub Actions"
  3. 推送代码 - 部署会自动进行

Vercel

点击上方的 "使用 Vercel 部署" 按钮或执行：

npx vercel

其他平台

此模板适用于任何支持 Next.js 的平台：

  • Netlify
  • Railway
  • Render
  • AWS Amplify

📁 项目结构

├── .github/
│   └── workflows/
│       └── deploy.yml      # GitHub Pages 部署配置
├── public/                 # 静态资源
│   └── images/            # 优化的图片资源
├── src/
│   ├── app/               # Next.js App Router
│   │   ├── layout.tsx     # 根布局与 providers
│   │   ├── page.tsx       # 首页
│   │   └── globals.css    # 全局样式和 Tailwind
│   ├── components/        # React 组件
│   │   ├── Counter.tsx    # 计数器演示（Zustand）
│   │   ├── TodoList.tsx   # 待办事项演示（动画）
│   │   ├── ThemeToggle.tsx # 主题切换器
│   │   └── ThemeProvider.tsx # 主题上下文提供者
│   └── store/             # Zustand 状态库
│       └── index.ts       # 全局状态管理
├── eslint.config.mjs      # ESLint 扁平配置
├── next.config.ts         # Next.js 配置
├── tailwind.config.ts     # Tailwind CSS v4 配置
└── tsconfig.json          # TypeScript 配置

🎨 样式系统

Tailwind CSS v4

  • 通过 CSS @config 指令配置
  • 自动深色模式，使用 dark: 变体
  • 在 globals.css 中自定义主题变量
  • 性能优化

深色模式

基于 next-themes 实现：

  • 系统偏好检测
  • 手动主题切换
  • 加载无闪烁
  • 持久化选择
  • CSS 变量主题

clsx 使用示例

// 条件类名
className={clsx(
  'base-class',
  {
    'active-class': isActive,
    'error-class': hasError,
  }
)}

// 多条件组合
className={clsx(
  'text-sm font-medium',
  isLarge && 'text-lg',
  color === 'primary' && 'text-blue-600'
)}

🔧 可用脚本

  • pnpm dev - 使用 Turbopack 启动开发服务器
  • pnpm build - 构建生产版本
  • pnpm start - 启动生产服务器
  • pnpm lint - 运行 ESLint
  • pnpm type-check - 检查 TypeScript 类型

🌟 状态管理

使用 TypeScript 的 Zustand 状态库：

// 计数器 store 示例
const { count, increment, decrement } = useCounterStore();

// 带持久化的任务 store
const { tasks, addTask, toggleTask } = useTaskStore();

特性：

  • Redux DevTools 集成
  • 持久化中间件
  • TypeScript 自动补全
  • 最少的样板代码

🎭 动画系统

集成 Motion（Framer Motion）：

// 简单动画
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  内容
</motion.div>

// 使用 AnimatePresence
<AnimatePresence mode="wait">
  {items.map(item => (
    <motion.div key={item.id} exit={{ opacity: 0 }}>
      {item.content}
    </motion.div>
  ))}
</AnimatePresence>

📝 代码规范

Git 提交

遵循 约定式提交：

  • feat: 新功能
  • fix: 修复问题
  • docs: 文档更新
  • style: 代码风格变化
  • refactor: 代码重构
  • test: 测试更新
  • chore: 维护任务

代码质量

  • ESLint 配合 Next.js 推荐规则
  • Prettier 保持一致的格式
  • Husky 实现预提交钩子
  • TypeScript 严格模式

🤝 贡献

  1. Fork 这个仓库
  2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
  3. 提交你的更改 (git commit -m 'feat: 添加神奇功能')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开一个 Pull Request

📄 许可证

MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

编码愉快！ 🎉