React实战：基于Vite和Redux Toolkit搭建任务协作看板项目

1. 项目概述：从一个奇怪的命名到完整的前端实战

先说个有意思的事。我第一次看到"rea"这个项目名时，第一反应是"Real"拼错了。后来拿到项目正文才知道，这是某位开发者给自己练手项目起的代号，全称其实是"React Experienced Application"，听说是他当时手滑少打了几个字母，索性就这么用下去了。这名字虽然随意，但项目本身一点不含糊——一个基于 React 生态从零搭建的任务协作管理面板，核心功能包括任务看板、列表切换、成员筛选和状态统计，数据用本地存储模拟后端接口，是典型的前端全流程练手项目。

这个项目适合谁？我觉得有三类人会很受用：一是刚学完 React 基础、想找个完整项目巩固的同学，二是准备面试前想梳理 React 知识体系的前端新人，三是平时做内部工具、需要快速搭一个管理后台的开发者。我自己当年也做过类似的库存管理系统，所以看到这个项目时很有感触，它几乎覆盖了 React 实战中八成的高频知识点，而且没有涉及复杂的后端配置，前端能独立跑通全流程。

从项目正文能看出，这个项目用了 Vite 做构建工具，React 18 版本，状态管理用的是 Redux Toolkit，UI 层自己手写的 CSS，没有引组件库。这种选型组合在真实业务里非常经得起推敲：Vite 冷启动快、配置轻，Redux Toolkit 是官方推荐的 Redux 写法，不引组件库则能练到原生 CSS 布局能力。整篇文章我会顺着项目的实际开发顺序走，先讲整体设计思路，再拆关键实现，然后给出完整实操流程，最后是问题排查记录，每部分都会补充我实际开发中踩过的坑和养成的习惯。

2. 项目整体设计与技术选型解析

2.1 为什么选 Vite 而不是 Create React App

项目正文里明确写了基于 Vite 构建，这是个非常务实的选择。CRA（Create React App）在早几年是 React 官方推荐脚手架，但它的开发服务器启动速度随着项目体积增长会明显变慢，热更新也不够跟手。Vite 用原生 ESM 按需编译，冷启动时间基本都在秒级，我在一个上百个组件的项目里实测过，Vite 的 dev server 启动比 CRA 快 3 倍以上，保存后的热更新几乎是即时的。

具体到"rea"这个项目，Vite 还有一个隐性优势：配置 Redux Toolkit 和路径别名时特别顺手。在 vite.config.js 里加一行resolve.alias就能用@/代替冗长的../，省掉 Webpack 时代一大堆 resolve 配置。以下是项目里实际用到的 Vite 配置核心片段：

// vite.config.js import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' import path from 'path' export default defineConfig({ plugins: [react()], resolve: { alias: { '@': path.resolve(__dirname, './src') } }, server: { port: 5173, open: true } })

这里有个细节值得注意：server.open设为true后，每次启动开发服务器会自动打开浏览器。刚开始开发时可能觉得烦，但它能帮你省掉手动切窗口的步骤，尤其是同时开着好几个终端的时候，这个配置能减少不少摩擦。

2.2 状态管理选 Redux Toolkit 的核心理由

"rea"项目的数据流比看上去要复杂：任务列表、筛选条件、成员列表、统计数字，这些状态散落在不同组件里。如果只用本地 state + props 层层传递，到后期任务数量上来后，每加一个新功能都要在一堆回调函数里找数据源头，排查起来非常痛苦。这正是 Redux Toolkit 发挥价值的场景。

Redux Toolkit 对传统 Redux 最大的改进是解决了模板代码地狱问题。传统 Redux 写一个模块要分别建 actionTypes、actions、reducer，还得用switch...case手写不可变更新逻辑。Redux Toolkit 的createSlice把这三者合并成一段代码，内部用 Immer 允许直接写"看起来像变异的"更新逻辑，实际生成的是不可变更新，心智负担小很多。

项目正文里有一段很典型的createSlice用法，我按我的习惯稍微整理过：

// store/taskSlice.js import { createSlice } from '@reduxjs/toolkit' const initialState = { tasks: [], filter: 'all', // all | active | completed selectedMember: null, stats: { total: 0, active: 0, completed: 0 } } const taskSlice = createSlice({ name: 'tasks', initialState, reducers: { addTask(state, action) { state.tasks.unshift(action.payload) updateStats(state) }, toggleTask(state, action) { const task = state.tasks.find(t => t.id === action.payload) if (task) { task.completed = !task.completed updateStats(state) } }, setFilter(state, action) { state.filter = action.payload }, setSelectedMember(state, action) { state.selectedMember = action.payload }, removeTask(state, action) { state.tasks = state.tasks.filter(t => t.id !== action.payload) updateStats(state) } } }) function updateStats(state) { state.stats.total = state.tasks.length state.stats.active = state.tasks.filter(t => !t.completed).length state.stats.completed = state.tasks.filter(t => t.completed).length } export const { addTask, toggleTask, setFilter, setSelectedMember, removeTask } = taskSlice.actions export default taskSlice.reducer

注意updateStats这个内部函数，它是直接改传入的state对象，这在传统 Redux 里是禁止的操作，但在 createSlice 里完全合法，因为 Immer 会帮你完成不可变转换。这是很多第一次用 Redux Toolkit 的人会困惑的地方，你可以放心大胆这样写，不过要记住这个函数必须定义在 reducers 内部，不能把它当作普通工具函数从外部模块引入，否则 Immer 的代理上下文就丢了。

2.3 不引组件库，手写 CSS 的得与失

现在的 React 项目普遍会引入 Ant Design 或 Element Plus 这类组件库，但"rea"项目选择了手写 CSS。这在一开始会拖慢开发进度，尤其是一个下拉筛选器或一个弹出确认框，手写起来远比调用现成组件麻烦。但从练手角度来看，这是一个非常有价值的选择。

手写 CSS 迫使你认真思考盒模型、Flex/Grid 布局、BEM 命名规范这些基础问题。我在项目过程中体会到，用组件库久了会产生一种"布局依赖症"——遇到任何界面问题第一反应是去查文档找现成组件，而不是从布局原理层面理解问题本质。亲手写一次任务看板的拖拽排列、筛选按钮的选中态、卡片的 hover 阴影过渡，你对 CSS 的理解深度完全不同。

项目正文里提到了一个很关键的布局细节：任务看板用 CSS Grid 实现三列布局，每列内部的任务卡片用 Flex 纵向排列。下面是我从中抽取并改进过的一段布局代码：

/* 看板三列布局：状态列 */ .board { display: grid; grid-template-columns: repeat(3, minmax(280px, 1fr)); gap: 16px; padding: 16px; align-items: start; } .board-column { display: flex; flex-direction: column; gap: 12px; background: #f7f8fa; border-radius: 8px; padding: 12px; min-height: 200px; } .task-card { background: #fff; border-radius: 6px; padding: 12px 14px; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08); transition: box-shadow 0.2s ease, transform 0.2s ease; } .task-card:hover { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12); transform: translateY(-2px); }

我特别推荐align-items: start这一行。你没加它之前，三列的高度会被最高的一列拉伸，结果就是左侧任务多、右侧任务少时，右侧那一列底部会留下大块空白，视觉上很突兀。加了align-items: start之后，每一列独立计算高度，这在所有 Grid 看板布局里都应该成为一个默认习惯。

3. 核心功能模块拆解与实现细节

3.1 任务看板的状态流设计与数据流转

"rea"项目核心页面是任务看板，它不是一个静态展示页，而是一个状态驱动的复杂视图。数据流的大致路径是：用户在输入框创建任务 → 触发dispatch(addTask(payload))→ Redux store 中的 tasks 数组更新 → 看板组件通过useSelector拿到最新任务列表 → 按照 filter 和 selectedMember 过滤 → 渲染到对应状态列。这个过程看起来不复杂，但里面有几个关键决策点直接影响体验。

第一个决策是"过滤应该由谁来做"。最省事的做法是在渲染前用useMemo对 tasks 做过滤，filter 变化时重新计算。但如果你把过滤结果也放进 Redux store，比如维护一份visibleTasks，就违背了单一数据源原则，因为 visibleTasks 永远可以由 tasks 和 filter 推导出来，存两份只会导致数据不同步的风险。项目里选择的是在组件层做派生状态，这种做法才是正确的思路。

第二个决策是任务数据模型设计。一个合格的任务对象至少需要这些字段：id、title、completed（或 status）、createdAt、memberId（负责人）、priority。项目正文里有一个我之前忽略的字段——createdAt，在后期做排序或"最近创建"视图时非常有用。如果你一上来就把这个字段省了，后面加功能时会发现测试数据已经积累了一堆，根本没有创建时间可以做排序，只能临时补字段，迁移起来很痛苦。

3.2 筛选与统计功能：派生状态的正确打开方式

筛选和统计是整个项目里最能体现 React 思维的部分。筛选器有三个维度：按状态（全部/进行中/已完成）、按成员（所有人/具体成员）、按优先级（可选）。这三个筛选条件可以组合使用，比如"只看某成员负责的已完成任务"，这时候绝对不能写三个独立的 if 判断来不断覆盖 previous 结果，而是应该用链式过滤。

我整理的组合筛选实现如下：

// 组件内派生状态 const visibleTasks = useMemo(() => { let result = tasks if (filter === 'active') { result = result.filter(t => !t.completed) } else if (filter === 'completed') { result = result.filter(t => t.completed) } if (selectedMember) { result = result.filter(t => t.memberId === selectedMember) } return result }, [tasks, filter, selectedMember])

这里用let和重新赋值的方式可能让某些严格遵循不可变数据的人不太舒服，你可以改用数组 reduce 或直接链式 filter：

const visibleTasks = useMemo(() => { return tasks .filter(t => filter === 'all' ? true : filter === 'active' ? !t.completed : t.completed) .filter(t => selectedMember ? t.memberId === selectedMember : true) }, [tasks, filter, selectedMember])

两种写法最终效果一样，但第二种更符合"每条过滤规则独立"的语义，可读性更好。而统计数字则要始终基于全量 tasks 计算，而不是基于筛选后的 visibleTasks，否则你筛选完会发现顶部的统计卡片数字也跟着变了，给用户带来误导。

3.3 本地持久化：localStorage 封装与体验优化

项目用到 localStorage 做数据持久化，这是个不错的折中方案：没有后端也能保住数据，刷新页面任务不丢失。但直接用原生 localStorage 一定踩坑，最经典的就是 JSON.parse 时报错。比如项目早期存的某个字段在后续代码里被改名了，旧数据解析出来就是 null，极端情况是整个数据结构对不上。

我建议在项目里加一个极简封装层：

// utils/storage.js const KEY = 'rea-tasks-v1' export function loadTasks() { try { const raw = localStorage.getItem(KEY) if (!raw) return { tasks: [], members: [] } const parsed = JSON.parse(raw) if (!Array.isArray(parsed.tasks)) return { tasks: [], members: [] } return parsed } catch (e) { console.warn('读取本地数据失败，已重置', e) return { tasks: [], members: [] } } } export function saveTasks(data) { try { localStorage.setItem(KEY, JSON.stringify(data)) } catch (e) { console.error('保存数据失败，可能是存储空间已满', e) } }

注意 KEY 里加了版本号v1，这是个容易被忽略的细节。因为 localStorage 的键一旦确定，之后你再改数据结构就会读出老版本的不兼容数据。提前规划版本号，将来升级时只需要判断版本号做迁移即可，不需要手动清缓存。

还有一个体验优化的点：不要每次 dispatch 后立刻同步写入 localStorage，可以考虑在 store 里加一个订阅监听，数据变化后做防抖保存。

// store/index.js import { configureStore } from '@reduxjs/toolkit' import taskReducer from './taskSlice' import { loadTasks, saveTasks } from '@/utils/storage' const preloadedState = loadTasks() const store = configureStore({ reducer: { tasks: taskReducer }, preloadedState }) let timer = null store.subscribe(() => { clearTimeout(timer) timer = setTimeout(() => { saveTasks({ tasks: store.getState().tasks.tasks }) }, 300) }) export default store

这里 300ms 的防抖足够应对绝大多数操作场景，用户快速添加或删除多个任务时不会频繁写磁盘，性能更好。

4. 完整实操：从零搭建一个 "rea" 看板项目

4.1 环境初始化与目录结构设计

实际操作的第一步是初始化项目。我建议直接使用 Vite 官方命令，选择 React 模板：

npm create vite@latest rea -- --template react

这一步会生成 React 18 + Vite 的基础结构。然后安装 Redux Toolkit 和 React Redux：

npm install @reduxjs/toolkit react-redux

这是"rea"项目唯一的两个运行时依赖，看到依赖这么少的时候就不要有"是不是少了点什么"的错觉，这个项目刻意保持依赖极简，这本身就是学习的好机会——只有自己动手封装，才能真正理解那些重型库帮你解决的问题。

然后规划目录结构。我修改后的目录如下：

src/ ├── components/ │ ├── TaskBoard.jsx │ ├── TaskColumn.jsx │ ├── TaskCard.jsx │ ├── TaskForm.jsx │ ├── FilterBar.jsx │ └── StatsPanel.jsx ├── store/ │ ├── index.js │ └── taskSlice.js ├── utils/ │ └── storage.js ├── hooks/ │ └── useTaskActions.js ├── App.jsx ├── main.jsx └── index.css

components 按组件职责拆分，store 集中状态管理，utils 放工具函数，hooks 放自定义逻辑。目录结构看着规范，但别为了规范而规范——如果你只有一个文件需要用到某个 hooks，直接写在组件里反而更清晰。

4.2 核心组件实现：表单、卡片、筛选器

核心组件中，TaskForm 负责创建新任务。它的实现有一个值得讲的细节：受控组件还是非受控组件。我的选择是受控，即输入框的值始终由 React state 管理，提交时才组装成一个任务对象。这样做的原因是未来可能加"输入时实时显示字数"这种需求，受控组件改起来成本更低。

组装任务对象时注意 id 不要用Date.now().toString()这种简单方式。如果同一毫秒内创建两个任务，id 会重复，React 渲染时 key 重复会导致奇怪的渲染 bug。推荐用crypto.randomUUID()，现代浏览器原生支持，一行代码解决问题：

// TaskForm.jsx 中的提交逻辑 function handleSubmit(e) { e.preventDefault() if (!title.trim()) return dispatch(addTask({ id: crypto.randomUUID(), title: title.trim(), completed: false, createdAt: new Date().toISOString(), memberId: selectedMember })) setTitle('') }

TaskCard 组件核心是交互反馈：点击卡片前面的复选框切换完成状态，点击删除按钮移除任务。这里有一个交互细节——删除按钮默认隐藏，hover 到卡片上才出现。这个模式在几乎所有任务管理工具里都有，但新手写的时候容易忽略掉 hover 事件与触摸设备的兼容性，在移动端就没有 hover 这个概念，所以我建议用媒体查询做兜底：

@media (hover: none) { .task-card .delete-btn { opacity: 1; } }

FilterBar 的实现逻辑不算复杂，就是三个按钮组（状态）+ 一个下拉选择框（成员），点击后 dispatch 对应的 action。这里核心注意点是按钮的选中态不应该用"有几个按钮就维护几个内部 state"的方式，而是直接读取 store 中的 filter 值来判断哪个按钮高亮，保证 UI 和状态同步。

4.3 看板渲染与空状态处理

看板的渲染逻辑是核心中的核心，这个环节最能看到一个人在写组件时有没有考虑边界情况。最基本的一个边界情况就是：某一列没有任何任务卡片时，如果直接不渲染任何东西，列头下面就是空白一片，用户会困惑"这一列是空还是加载失败？"

项目里给每个列增加了一个空状态提示：

<> <h3>{columnTitle}</h3> {tasks.length === 0 ? ( <div className="empty-tip">暂无任务，点击上方按钮创建</div> ) : ( tasks.map(task => ( <TaskCard key={task.id} task={task} /> )) )} </>

这个空状态提示在真实产品中极其常见，但它也是最容易被开发遗漏的细节。一个有经验的开发者在写一个列表类组件时，前 30 分钟可能就完成了数据渲染逻辑，剩下 70% 的时间都在考虑空状态、加载状态、错误状态。

为了演示完整效果，我在本地为"rea"项目预置了三条不同状态的模拟数据：

• 一条"编写季度技术总结"任务，状态为待处理，负责人为某成员甲，优先级标记为高
• 一条"重构任务看板拖拽逻辑"，状态为进行中，负责人为成员甲，创建时间是两周前
• 一条"修复登录页响应式样式"，状态为已完成，优先级标记为低

这三个条目的数据格式完全按照 taskSlice 里的初始结构写入 localStorage 后初始化项目，这样刷新页面后就能直接看到看板三列的渲染效果。

4.4 组件通信模式与自定义 Hook 封装

组件之间的通信方式，在"rea"项目里有两种体现：一是通过 Redux 的全局状态共享，二是通过 props 逐级传递。前者适合跨多层组件共享的数据，比如成员列表；后者适合父子组件之间局部状态，比如 TaskForm 里的表单输入值。

在实际开发中，我习惯把和 Redux 交互的逻辑抽成自定义 Hook，这样组件代码看起来会很干净，将来做测试也方便 mock。项目里可以加一个useTaskActions：

// hooks/useTaskActions.js import { useDispatch } from 'react-redux' import { useCallback } from 'react' import { addTask, toggleTask, removeTask, setFilter, setSelectedMember } from '@/store/taskSlice' export function useTaskActions() { const dispatch = useDispatch() const handleAdd = useCallback((payload) => dispatch(addTask(payload)), [dispatch]) const handleToggle = useCallback((id) => dispatch(toggleTask(id)), [dispatch]) const handleRemove = useCallback((id) => dispatch(removeTask(id)), [dispatch]) const handleSetFilter = useCallback((filter) => dispatch(setFilter(filter)), [dispatch]) const handleSetMember = useCallback((memberId) => dispatch(setSelectedMember(memberId)), [dispatch]) return { handleAdd, handleToggle, handleRemove, handleSetFilter, handleSetMember } }

用useCallback包一层是为了保证 props 传递时引用稳定，减少子组件不必要的 re-render。这个项目表面上看组件树不深，用不上性能优化，但养成这种习惯会让你在面对大型项目时少踩很多次重复渲染的坑。

4.5 样式细节与响应式适配

移动端适配是项目实现阶段最容易忽略的环节，因为桌面浏览器开发时窗口宽度固定，很难自然触发移动端断点。"rea"项目在 CSS 里加了一组媒体查询，我按常用尺寸拆解如下：

响应式断点策略：

• 默认（> 640px）：三列看板，充分利用宽度
• 640px 以下：看板切为单列，列之间用间距分隔，避免横向滚动
• 500px 以下：任务卡片内边距压缩，删除按钮常驻显示以便触控

这里有一个具体的坑：如果你把grid-template-columns写死为repeat(3, 1fr)，在手机上是无法自动变单列的，必须用媒体查询强制覆盖。

@media (max-width: 640px) { .board { grid-template-columns: 1fr; gap: 12px; } }

另一个细节是box-sizing。我自己在空闲时间做项目时往往会忘记在全局 CSS 里设置一条* { box-sizing: border-box; }，导致 width、padding、border 加起来超出容器宽度，出现莫名其妙的对不齐。这个项目里我特意检查过，在 index.css 第一行就设了这条，后面再写任何宽度相关样式时都少了这一个坑。

5. 开发中的常见问题与排查技巧实录

5.1 Redux 里修改了 state 但页面不刷新排查流程

这个问题在"rea"项目开发中大概率会遇到。它的核心原因是扁平化改变脱离了 Immer 的监听范围，比如直接对 state 里的某个对象属性赋值而不是返回新引用，或者直接在createSlice外部修改了 store 数据。

排查步骤我总结为三条：

• 第一步，在组件里打印useSelector取到的值，确认 Redux 里有没有变化。
• 第二步，打印 dispatch 的函数返回值，确认 action 是否被发出。
• 第三步，检查 reducer 里是否返回了新的 state 引用，如果没有，可以打开 Redux DevTools 查看状态历史，时间旅行能直接看出哪一步没有生效。

这个排查流程适用于绝大多数 Redux 状态不更新问题，值得背下来。

5.2 刷新页面后数据丢失与 localStorage 清空

开发初期你可能会发现：明明加了saveTasks，但刷新后数据还是没了。最可能的原因是 store 初始化时没有读取已经保存的数据，而是每次都用initialState里的空数组。预加载的状态才是关键，也就是configureStore的preloadedState参数必须从loadTasks()拿。

还有一个常见原因是 localStorage 写入失败。不是每次都会失败，但隐私模式或存储空间不足时，setItem会静默抛异常，被 try/catch 吞掉后你完全无感知。我建议在开发模式下把保存失败的信息打印到控制台，这样 debug 时至少能看到线索。

5.3 中文输入法导致表单 enter 事件重复触发的怪异问题

这个坑非常隐蔽，而且极其折腾。当用户在中文输入法下输入任务标题后，按 Enter 键来确认拼音候选词时，部分浏览器会同时触发键盘的 keydown 事件，如果这个 keydown 绑定了表单提交逻辑，就会导致拼音还没选完就提交了一个"半截"任务。

解决方案是给表单提交事件绑定onSubmit而非onKeyDown，并且不监听裸的键盘 ENTER 事件。利用<form>的语义化提交机制，浏览器会在输入法确认后才触发 submit。如果你必须使用 keydown 监听，可以在 keydown 处理函数里判断e.isComposing，这个属性在输入法组合期间为true，可以过滤掉误触事件。

我实测过这个方案，在 Chrome 和 Edge 下都工作正常，这是很多新手被坑了几天才找到答案的老问题。

6. 性能优化、状态管理进阶与进一步拓展方向

随着项目越做越大，你可能会关心优化层面的问题。React 的memo组件可以做：如果 TaskCard 的 props 没变、Redux 中的相关状态没变，就不重新渲染卡片。注意在 Redux Toolkit 中，useSelector返回新数组时如果不做比较，每次 action 后组件都会重新渲染。解决方法是让 selector 只挑选最小依赖的数据，而不是拿整棵 state 树。

项目后期可以考虑的优化方向，我用一张表格梳理：

方向	具体做法	解决的问题
拖拽排序	引入 dnd-kit 或自己写 Pointer Events 实现跨列拖拽	看板质感提升，操作更直观
服务端持久化	接 REST API 或 Firebase，同步 localStorage 数据到云端	多端数据互通
分类标签	在任务对象中加入 tags 字段	扩展筛选维度
主题切换	CSS Variables 配合切换按钮	提升用户体验
单元测试	用 Vitest + Testing Library 覆盖 taskSlice 与 FilterBar	保障核心逻辑回归安全

我特别推荐先做单元测试这个方向，因为 taskSlice 是纯函数式的状态逻辑，测试它不需要渲染任何组件，跑起来非常快，测试体验也会特别好。等你习惯了这个模式，再逐步给组件加交互测试。

7. 我在实操过程中积累的几个习惯与感受

最后分享几个我在复现"rea"这些功能时的个人体会，可能会对你调整开发节奏有帮助。

第一个习惯是"先画数据流图再写代码"。这不是什么很高大上的过程，就是在纸上大致画出：哪个组件触发哪个 action，state 如何变化，哪个组件通过什么选择器读数据。很多初学者实际上不是不会写代码，而是头脑中缺少一张状态信任地图。花 10 分钟画着画着，你就会理清楚哪些状态应该放 Redux、哪些应该留在组件内。

第二个习惯是"时刻保持组件精简"。我在给"rea"扩展拖拽功能和主题切换时，能明显感受到组件一旦臃肿，改起 bug 来就越痛苦。如果发现某个组件里同时处理了展示和业务逻辑，写的代码超过 150 行时，就要考虑是不是该拆分了。

第三个感受是"小项目成就感会被慢慢堆积"。像这种"对比 CRA 冷启动、对比本地 state 复杂性"的自我反馈，一轮一轮做完之后，你会发现自己对 React 架构的理解不再停留在单个 API 层面，而是有了整体规划的感觉。很多基础其实都是在这样的小项目中磨出来的。

如果你刚学完 React 还不太确定下一步干什么，或者正在做简历里需要一点项目支撑，我建议你留出一个周末时间，把这个前端看板完完整整过一遍。我保证过程中犯的错误、查的资料、修好的 bug，会是你对整个 React 生态从"会用"到"懂用"最踏实的起点。