张翔
256 lines
6.4 KiB
Markdown
256 lines
6.4 KiB
Markdown
# Novalon Website
|
||
|
||
这是一个基于 Next.js 16 构建的现代化静态网站项目，采用 React 19 和 TypeScript 技术栈。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Next.js 16.1.6 (App Router)
|
||
- **语言**: TypeScript 5
|
||
- **UI 库**: React 19.2.3 + React DOM 19.2.3
|
||
- **样式**: Tailwind CSS v4 + CSS Variables
|
||
- **组件库**: shadcn/ui (基于 Radix UI)
|
||
- **动画**: Framer Motion 12.29.2
|
||
- **图标**: Lucide React 0.563.0
|
||
- **工具库**:
|
||
- `clsx` - 条件类名合并
|
||
- `tailwind-merge` - Tailwind 类名智能合并
|
||
- `class-variance-authority` - CVA 变体管理
|
||
- `zod` - 数据验证
|
||
|
||
## 项目特性
|
||
|
||
- ✨ **现代化 UI** - 基于 shadcn/ui 的精美组件设计
|
||
- 🎨 **主题支持** - CSS Variables 驱动的深色/浅色主题
|
||
- 📱 **响应式设计** - 完美适配各种屏幕尺寸
|
||
- 🚀 **静态导出** - 支持静态 HTML 输出
|
||
- 🔧 **类型安全** - 完整的 TypeScript 支持
|
||
- 📦 **代码分割** - 自动按路由代码分割
|
||
- 🎯 **路径别名** - 使用 `@/*` 别名导入
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 18+
|
||
- npm / yarn / pnpm / bun
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
# 或
|
||
yarn install
|
||
# 或
|
||
pnpm install
|
||
# 或
|
||
bun install
|
||
```
|
||
|
||
### 开发模式
|
||
|
||
启动开发服务器：
|
||
|
||
```bash
|
||
npm run dev
|
||
# 或
|
||
yarn dev
|
||
# 或
|
||
pnpm dev
|
||
# 或
|
||
bun dev
|
||
```
|
||
|
||
访问 [http://localhost:3000](http://localhost:3000)
|
||
|
||
### 构建生产版本
|
||
|
||
构建静态导出：
|
||
|
||
```bash
|
||
npm run build
|
||
# 或
|
||
yarn build
|
||
# 或
|
||
pnpm build
|
||
# 或
|
||
bun build
|
||
```
|
||
|
||
输出目录: `dist/`
|
||
|
||
### 启动生产服务器
|
||
|
||
```bash
|
||
npm start
|
||
# 或
|
||
yarn start
|
||
# 或
|
||
pnpm start
|
||
# 或
|
||
bun start
|
||
```
|
||
|
||
### 代码检查
|
||
|
||
```bash
|
||
npm run lint
|
||
# 或
|
||
yarn lint
|
||
# 或
|
||
pnpm lint
|
||
# 或
|
||
bun lint
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
novalon-website/
|
||
├── src/
|
||
│ ├── app/ # Next.js App Router 页面
|
||
│ │ ├── layout.tsx # 根布局文件
|
||
│ │ ├── page.tsx # 首页
|
||
│ │ ├── globals.css # 全局样式
|
||
│ │ └── [routes]/ # 动态路由
|
||
│ ├── components/ # React 组件
|
||
│ │ ├── ui/ # shadcn/ui 基础组件
|
||
│ │ └── ... # 业务组件
|
||
│ ├── lib/ # 工具函数和配置
|
||
│ │ └── utils.ts # cn() 工具函数
|
||
│ └── assets/ # 静态资源
|
||
├── public/ # 公共静态资源
|
||
├── dist/ # 构建输出目录（静态导出）
|
||
├── next.config.ts # Next.js 配置
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── tailwind.config.* # Tailwind CSS 配置
|
||
├── components.json # shadcn/ui 配置
|
||
└── package.json
|
||
```
|
||
|
||
## 路径别名
|
||
|
||
项目配置了以下路径别名：
|
||
|
||
| 别名 | 映射路径 | 示例 |
|
||
| -------------- | --------------------- | ---------------------- |
|
||
| `@/*` | `./src/*` | `@/components/Button` |
|
||
| `@/components` | `./src/components` | @/components/ui/button |
|
||
| `@/lib` | `./src/lib` | @/lib/utils |
|
||
| `@/ui` | `./src/components/ui` | @/ui/button |
|
||
| `@/hooks` | `./src/hooks` | @/hooks/useToggle |
|
||
|
||
## 主要依赖
|
||
|
||
### 生产依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
| ------------------------ | ------- | ----------------- |
|
||
| next | 16.1.6 | React 全栈框架 |
|
||
| react | 19.2.3 | UI 库 |
|
||
| react-dom | 19.2.3 | React DOM 渲染 |
|
||
| framer-motion | 12.29.2 | 动画库 |
|
||
| lucide-react | 0.563.0 | 图标库 |
|
||
| @radix-ui/react-\* | - | 无状态可访问组件 |
|
||
| tailwind-merge | 3.4.0 | Tailwind 类名合并 |
|
||
| class-variance-authority | 0.7.1 | 变体类名管理 |
|
||
| clsx | 2.1.1 | 条件类名合并 |
|
||
| zod | 4.3.6 | 数据验证 |
|
||
|
||
### 开发依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
| ------------------ | ------ | ------------------- |
|
||
| typescript | 5 | 类型系统 |
|
||
| tailwindcss | 4 | CSS 框架 |
|
||
| @types/node | 20 | Node.js 类型 |
|
||
| @types/react | 19 | React 类型 |
|
||
| @types/react-dom | 19 | React DOM 类型 |
|
||
| eslint | 9 | 代码检查 |
|
||
| eslint-config-next | 16.1.6 | Next.js ESLint 配置 |
|
||
|
||
## 配置说明
|
||
|
||
### Next.js 配置 (`next.config.ts`)
|
||
|
||
```typescript
|
||
import type { NextConfig } from "next";
|
||
|
||
const nextConfig: NextConfig = {
|
||
output: "export", // 静态导出模式
|
||
distDir: "dist", // 输出目录
|
||
images: {
|
||
unoptimized: true, // 静态导出需要禁用图片优化
|
||
},
|
||
};
|
||
|
||
export default nextConfig;
|
||
```
|
||
|
||
### TypeScript 配置 (`tsconfig.json`)
|
||
|
||
- 目标: ES2017
|
||
- 模块: ESNext (bundler)
|
||
- 严格模式: 启用
|
||
- JSX: react-jsx
|
||
- 路径别名: `@/*` → `./src/*`
|
||
|
||
### Tailwind CSS
|
||
|
||
使用 Tailwind CSS v4，采用 CSS-first 配置方式，通过 CSS Variables 实现主题定制。
|
||
|
||
### shadcn/ui 配置
|
||
|
||
- 风格: New York
|
||
- RSC 支持: 启用
|
||
- CSS 变量: 启用
|
||
- 前缀: 空
|
||
- RTL: 禁用
|
||
- 图标库: Lucide
|
||
|
||
## 构建输出
|
||
|
||
运行 `npm run build` 后：
|
||
|
||
- 静态文件输出到 `dist/` 目录
|
||
- 包含静态 HTML、CSS、JavaScript 文件
|
||
- 图片未优化（因为使用了 `unoptimized: true`）
|
||
|
||
可以直接部署到任何静态托管服务：
|
||
|
||
- Vercel
|
||
- Netlify
|
||
- GitHub Pages
|
||
- AWS S3 + CloudFront
|
||
- 阿里云 OSS
|
||
- 腾讯云 COS
|
||
|
||
## 命令速查
|
||
|
||
| 命令 | 描述 |
|
||
| --------------- | ------------------------ |
|
||
| `npm run dev` | 启动开发服务器 |
|
||
| `npm run build` | 构建生产版本（静态导出） |
|
||
| `npm run start` | 启动生产服务器 |
|
||
| `npm run lint` | 运行 ESLint 检查 |
|
||
|
||
## 浏览器支持
|
||
|
||
- Chrome (最新 2 个版本)
|
||
- Firefox (最新 2 个版本)
|
||
- Safari (最新 2 个版本)
|
||
- Edge (最新 2 个版本)
|
||
|
||
## 学习资源
|
||
|
||
- [Next.js 文档](https://nextjs.org/docs)
|
||
- [React 文档](https://react.dev)
|
||
- [TypeScript 文档](https://www.typescriptlang.org/docs)
|
||
- [Tailwind CSS 文档](https://tailwindcss.com/docs)
|
||
- [shcn/ui 文档](https://ui.shadcn.com)
|
||
- [Framer Motion 文档](https://www.framer.com/motion)
|
||
- [Lucide 图标](https://lucide.dev)
|
||
|
||
## 许可证
|
||
|
||
本项目仅供学习和参考使用。
|