# next-app-template **Repository Path**: msxn/next-app-template ## Basic Information - **Project Name**: next-app-template - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-22 - **Last Updated**: 2026-05-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Next.js 企业级应用模板 > React 官方推荐、自带 SSR / SEO / 路由的企业级终极方案 ## 技术栈 | 类别 | 技术 | 版本 | |------|------|------| | 框架 | Next.js | 16.2.4 | | UI | React | 19.2.4 | | 语言 | TypeScript | 5 | | 样式 | Tailwind CSS | v4 (CSS-first) | | 代码检查 | ESLint | 9 (Flat Config) | | 代码格式化 | Prettier | 3 | | 字体优化 | next/font | 内置 | ## 快速开始 ```bash # 安装依赖 npm install # 启动开发服务器 npm run dev # 生产构建 npm run build # 生产预览 npm run start ``` ## 开发命令 | 命令 | 说明 | |------|------| | `npm run lint` | ESLint 代码检查 | | `npm run lint:fix` | ESLint 自动修复 | | `npm run format` | Prettier 格式化所有文件 | | `npm run format:check` | 检查 Prettier 格式 | ## 目录结构 ``` ├── src/ # 源代码目录 │ └── app/ # App Router │ ├── layout.tsx # 根布局 │ ├── page.tsx # 首页 │ ├── globals.css # 全局样式 │ └── favicon.ico ├── public/ # 静态资源 ├── package.json ├── tsconfig.json # TS 配置（@/* → src/*） ├── next.config.ts # Next.js 配置 ├── eslint.config.mjs # ESLint Flat Config ├── .prettierrc # Prettier 配置 ├── .prettierignore # Prettier 忽略 └── postcss.config.mjs # PostCSS 配置 ``` ## 核心特性 ### SSR / SEO / 路由 - **服务端渲染 (SSR)**：`src/app/` 下文件默认为 Server Components，SSR 默认开启 - **SEO 优化**：Metadata API 动态生成 `` 标签 - **文件系统路由**：`src/app/` 下的文件自动映射路由 ### Tailwind CSS v4 采用 CSS-first 配置，无需 `tailwind.config.js`： ```css @import 'tailwindcss'; @theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --font-sans: var(--font-geist-sans); } ``` ### Server / Client 组件 - **Server Components（默认）**：数据获取、SEO 敏感内容 - **Client Components**：交互组件添加 `"use client"` 指令 ## 开发规范 ### 路径别名 ```typescript import Button from '@/components/Button'; import styles from '@/styles/Home.module.css'; ``` ### 字体加载 ```typescript import { Geist, Geist_Mono } from 'next/font/google'; const geistSans = Geist({ variable: '--font-geist-sans', subsets: ['latin'], }); ``` ### Metadata API ```typescript export const metadata: Metadata = { title: '应用标题', description: '应用描述', }; ``` ## Harness 使用规范 本模板基于 **Long-Running Agent Harness v3.5** 设计，支持多会话开发和 Agent Teams 协作。 ### 核心文件 | 文件/目录 | 说明 | |-----------|------| | `.harness/` | Harness 根目录，存放特征跟踪和上下文 | | `.harness/features.json` | 特征跟踪列表（F001、F002...） | | `.harness/context_summary.md` | 架构决策、模式和陷阱记录（每次会话必读） | | `.harness/harness.json` | 项目元数据、Git 身份、团队结构 | | `.harness/init.sh` | 构建/测试脚本（smoke_test / full_test） | | `.claude/hooks/` | 质量门禁钩子 | ### Hooks 质量门禁 | Hook | 触发时机 | 作用 | |------|----------|------| | `enforce-scope.sh` | Edit/Write 前 | 阻止修改范围外的文件 | | `verify-git-identity.sh` | Bash git 命令前 | 验证 Git 身份一致性 | | `verify-task-quality.sh` | TaskCompleted | 运行测试，失败则拒绝 | | `check-remaining-tasks.sh` | TeammateIdle | 检查剩余特征，驱动连续工作 | | `post-task-complete.sh` | TaskCompleted 后 | 更新特征状态和进度 | ### 特征工作流 ``` 特征定义 → scope 划定 → 实现 → 测试验证 → status: "passing" ``` 特征完成标准： - `status` = `"passing"` - `test_file` 指向测试文件 - `coverage` >= 95% ### 开发会话流程 1. **会话开始**：读取 `.harness/context_summary.md` + `TaskList` 2. **开发中**：严格在 assigned scope 内工作 3. **会话结束**：更新 `features.json` 状态 + `claude-progress.txt` 4. **上下文压缩后**：立即恢复状态再继续 ### 团队协作（可选） 如启用 Agent Teams： - 每个 teammate 有独立 scope - Reviewer 角色负责代码审查 - 通过 `team-lead` 协调任务分配 ## 生产部署 推荐 [Vercel](https://vercel.com)： ```bash npm run build npm run start # 本地预览 ``` ## 学习资源 - [Next.js 文档](https://nextjs.org/docs) - [App Router 指南](https://nextjs.org/docs/app) - [Tailwind CSS v4](https://tailwindcss.com/docs) - [React 19](https://react.dev)