# template-react19-vite7

**Repository Path**: niaoyu-template/template-react19-vite7

## Basic Information

- **Project Name**: template-react19-vite7
- **Description**: React19 + Vite7 + ts(Typescript) + scss + TailWindcss 的 demo 项目，拉取后可直接使用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-05
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React19 + Vite7 + TypeScript 项目模板

**React19 + Vite7 + TypeScript + SCSS + TailwindCSS 的模板项目，拉取后可直接使用**

## 📚 目录

- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [环境配置](#环境配置)
- [开发工具](#开发工具)
- [参考资料](#参考资料)

## 🚀 快速开始

### 安装依赖

```shell
npm i
# 或
pnpm install
```

### 启动开发环境

```shell
npm run dev
# 或
pnpm dev
```

然后在 8383 端口访问项目，端口配置在 `.env.development` 文件中，可以自行修改。

### 打包项目

```shell
npm run build
# 或
pnpm build
```

会生成 `dist` 文件夹，里面是打包完成后的静态项目。

## 🏗️ 项目结构

```
src/
├── App.tsx            # 应用入口组件
├── api/               # API 接口
├── assets/            # 静态资源
├── components/        # 公共组件
├── hooks/             # 自定义 Hooks
├── main.tsx           # 应用入口文件
├── pages/             # 页面组件
├── router/            # 路由配置
├── store/             # 状态管理
├── types/             # 类型定义
├── utils/             # 工具函数

```

## ⚙️ 环境配置

默认启动 `npm run dev` 时，启动的是开发环境，会自动载入 `.env.development` 和 `.env` 两个配置文件。

执行 `npm run build` 构建时，会自动载入 `.env.production` 和 `.env` 两个配置文件。

### 添加自定义环境

如果需要添加一个新的环境（如 **test**），可以进行以下操作：

1. 添加 `.env.test` 配置文件，写入环境变量

2. 在 `package.json` 中添加两个指令：
   - 启动 test 的开发环境：`"test": "vite --mode test"`
   - 打包构建 test 环境的包：`"build:test": "tsc -b && vite build --mode test"`

3. 执行 `npm run test` 或 `npm run build:test` 时，会自动载入 `.env.test` 和 `.env` 两个配置文件

详见 [Vite 环境变量和模式](https://cn.vitejs.dev/guide/env-and-mode)。



## 🔧 开发工具

### useDepLog Hook

项目内置了一个强大的依赖项调试工具 `useDepLog`，用于追踪 React Hook 依赖项的变化，帮助开发者快速定位性能问题和不必要的重新渲染。

#### 功能特性

- ✅ **精确追踪**：使用 `Object.is` 进行严格比较，与 React 内置 Hook 行为一致
- ✅ **全面检测**：检测依赖项的新增、删除、修改和类型变化
- ✅ **智能分类**：区分函数和非函数类型，提供不同的日志输出
- ✅ **彩色输出**：使用不同颜色标识不同类型的变化（新增🟢、删除🔴、修改🔵）
- ✅ **性能优化**：生产环境下自动禁用，零性能开销
- ✅ **时间戳**：每次输出都包含时间戳，便于调试

#### 使用方法

```typescript
import { useDepLog } from '@/hooks/useDepLog';

function MyComponent({ count, name, onUpdate }) {
  const [state, setState] = useState(0);
  const memoValue = useMemo(() => count * 2, [count]);
  
  // 追踪 useEffect 的依赖项变化
  useDepLog({ count, name, onUpdate }, 'MyComponent-useEffect');
  
  useEffect(() => {
    // 你的 effect 逻辑
  }, [count, name, onUpdate]);
  
  // 追踪 useMemo 的依赖项变化
  useDepLog({ count }, 'MyComponent-useMemo');
  
  // 追踪多个状态变化
  useDepLog({ state, memoValue, count }, 'MyComponent-状态追踪');
  
  return <div>{/* 组件内容 */}</div>;
}
```

#### 输出示例

当依赖项发生变化时，控制台会输出类似以下的信息：

```
▼ MyComponent-useEffect - 14:30:25
  变化者：count { 旧: 1, 新: 2 }
  变化者：onUpdate (function)
  变化者：name (新增) { 旧: undefined, 新: "张三" }
```

#### 最佳实践

1. **临时使用**：建议在调试时临时添加，问题解决后移除
2. **有意义的命名**：使用描述性的 `hookName` 便于区分不同的调试点
3. **精确追踪**：只追踪你关心的依赖项，避免信息过载

```typescript
// ✅ 推荐：精确追踪特定依赖
useDepLog({ userId, filters }, 'UserList-数据获取');

// ❌ 不推荐：追踪过多不相关的依赖
useDepLog({ ...props, ...state, ...context }, '全部状态');
```

#### 环境说明

- **开发环境**：正常工作，输出详细的调试信息
- **生产环境**：自动禁用，不会影响应用性能

### 打包时间戳

项目在打包时会自动注入打包时间戳，页面加载后会将打包时间存储到 `localStorage.buildTime` 中，格式为北京时间 `YYYY-MM-DD HH:mm:ss`，便于版本追踪和调试。

## 📖 参考资料

- [React 官方文档](https://react.dev/)
- [Vite 官方文档](https://cn.vitejs.dev/)
- [TypeScript 官方文档](https://www.typescriptlang.org/docs/)
- [Tailwind CSS 官方文档](https://tailwindcss.com/docs)
- [shadcn/ui 组件文档](https://ui.shadcn.com/docs/components)
- [Radix UI 文档](https://www.radix-ui.com/primitives/docs/overview/introduction)
- [Lucide 图标库](https://lucide.dev/icons/)