全栈项目从零到上线：TaskFlow实战系列之开发环境搭建

很多关注我的朋友后台催了好几次想学一个完整项目但不知道从哪下手网上教程要么是零散的知识点要么一上来就甩一堆代码装完环境就卡住了。所以这次我干脆把带项目的全过程整理成一个连载系列——从技术选型、环境搭建开始一路写到前后端联调、容器化部署每一章都是真实推进不是录播稿。今天是第01章先把课程的整体规划讲清楚然后直接“项目启航”把开发环境跑起来。本次实战我会带大家做一个轻量级的团队任务协作平台类似简化版看板工具无论你是刚学完基础语法想找个完整项目练手的同学还是做了几年业务开发但没自己从零搭过项目的朋友这套内容都有参考价值。1. 这个系列到底要带你做什么1.1 为什么想做这么一套实战连载先说点实话。市面上不缺教程缺的是“能跟着做完的一条完整主线”。我见过太多朋友刷了三个月教程语法都会一问“你独立做过什么项目”就哑火。为什么因为零零散散的知识点没有串成一条线今天学个组件、明天学个 API最后都不知道这些东西在真实项目里怎么配合。所以我设计这套实战连载的时候给自己定了一个原则不搞知识拼盘只走完整项目。每一个章节都对应项目推进中的一个真实阶段学完一章项目就往前走一步代码量、架构复杂度都是渐进式增加的。你跟着做完手里会有一个能跑、能部署、能拿出去讲的项目而不是几十个“hello world”的截图。另外我也想让这个系列照顾到不同基础的人。基础偏弱的朋友可以把我写的每一步都当作标准答案去执行先跑通再理解已经有过开发经验的朋友则可以重点关注章节里的技术选型逻辑、目录结构设计、以及我踩过的那些坑这些是短平快教程不会写的东西。1.2 我们最终要做出一个什么东西我选的项目是团队任务协作平台。为什么选它因为这类项目天然具备几个特点有用户体系、有核心业务逻辑任务的增删改查、有状态流转待办/进行中/已完成、有权限控制成员vs管理员、有前后端交互复杂度。这些基本上覆盖了一个业务系统最常见的核心场景学完一个以后遇到类似管理系统都能迁移思路。具体功能清单如下用户注册与登录基于 Token 的身份认证项目空间的创建与成员邀请任务的创建、编辑、删除、拖动切换状态评论功能围绕任务做简单讨论基于角色的权限控制普通成员和管理员权限不同前端看板视图三列拖拽交互Docker Compose 一键启动本地依赖部署到云服务器用 Nginx 反向代理前后端最终形态是一个前后端分离的 Web 应用后端提供 JSON API前端使用 React 渲染界面数据库放在容器里。这个项目做完你不只是会写几个接口而是能讲清楚“一个 Web 业务系统从零到上线到底经历了什么”。2. 课程地图四阶段走完全程2.1 阶段一地基工具链、TypeScript、数据库这个阶段不急着写业务代码。我们要先把工具链理顺Node.js 环境怎么装、包管理器用哪个、TypeScript 怎么配置、数据库怎么跑起来、表结构怎么设计。说白了这一步的目标是“让开发环境听你指挥”而不是每次写代码前先跟环境搏斗半小时。数据库设计是这一阶段的重头戏。我会带着你把用户表、项目表、任务表、评论表的关系理清楚用 Prisma 定义 Schema然后生成数据库表结构。很多初学者喜欢一上来就写业务逻辑结果写到一半发现表结构设计有缺陷又回头改白白浪费大量时间。地基阶段就是在帮你避免这个问题。2.2 阶段二后端 API 与核心业务逻辑第二阶段进入后端开发。我们会用 Express TypeScript 搭建 RESTful API实现注册登录、认证中间件、任务的增删改查、成员权限管理等核心接口。写代码之外我还会重点讲几个“为什么”为什么用 JWT 而不是 Session、为什么接口要分层、为什么错误处理要统一。这一阶段会穿插大量调试技巧。比如用 Postman 或 Apifox 调试接口时怎么快速定位是参数问题还是服务端逻辑问题比如拿到一个 500 错误应该先看日志还是先看代码。这些实操经验是文档里不会直接教但工作中天天要用的。2.3 阶段三前端界面与交互第三阶段切换到前端。我们用 React Vite TypeScript 从零搭建界面层包括登录页、看板页、任务详情弹窗、成员管理页。状态管理用 Zustand这是一套轻量方案比 Redux 少了很多样板代码非常适合中小型项目。接口请求用统一的封装模块把 token 注入、错误提示、loading 状态集中处理。交互方面看板拖拽会用到 dnd-kit 这个库。它比较轻API 设计也清晰。这一阶段做完前端页面就全部能跑通了你会看到数据从后端来、渲染在界面上、操作后又写回数据库的完整链路。2.4 阶段四联调、部署与上线最后一个阶段是很多人没接触过的“最后一公里”。我们要做前后端联调、写 Dockerfile、用 Docker Compose 编排前后端和数据库部署到一台云服务器上域名解析、HTTPS 证书、Nginx 反向代理、进程守护全部走一遍。部署这件事很多课程把它放在最后“有时间就讲”但我认为它恰恰是项目能不能真正拿得出手的关键。一个只能在本机 localhost 跑的项目面试时说服力是很弱的。等你看到项目通过公网域名访问的那一刻整个实战系列才算真正闭环。3. 项目启航从零搭起开发环境3.1 技术栈选型为什么是这一套正式动手之前先把你接下来会反复见到的技术栈列清楚。为了避免“每个技术看起来都对但不知道选哪个”的迷茫我直接给出本次项目的选型结果并解释每一项背后的考量技术选择核心原因后端框架Express 4生态成熟、中间件丰富、学习曲线平缓适合作为第一个全栈项目前端框架React 18组件化思维通用性强岗位需求量大生态完善开发语言TypeScript 5类型系统能在编译期拦截大量低级错误长期维护成本低数据库PostgreSQL 16功能全面、JSON 支持好和 Prisma 配合体验稳定ORMPrisma 5Schema 直观、迁移流程清晰、文档友好对新手比写原生 SQL 更友好包管理器pnpm 9节省磁盘空间、安装速度快、依赖隔离严格构建工具Vite 5冷启动速度快开发体验明显优于 Webpack 时代状态管理ZustandAPI 极简几乎没有模板代码适合中小型项目拖拽库dnd-kit轻量、无障碍支持好、React 18 兼容性正确你可能注意到我选的东西都比较“主流”。这是我的一个经验实战项目的技术选型稳定和生态优先不要追求冷门炫技。你选一个小众数据库、一个刚出的框架版本遇到问题可能连搜索都搜不到答案会极大消耗学习热情。3.2 第一步安装基础运行时先说 Node.js。这个项目全程依赖 Node后面前端构建、后端运行、各种工具链都建立在它上面。我不建议直接去官网下载最新版而是先装一个 Node 版本管理器推荐 nvm-windowsWindows或 nvmmacOS/Linux。为什么要多此一举因为不同项目对 Node 版本要求不一样你今天跟着这个系列用 Node 20明天公司老项目可能要用 Node 16没有版本管理器就得反复卸载安装装了管理器之后随时切换# Windows 用户先安装 nvm-windows然后执行 nvm install 20 nvm use 20 # macOS/Linux 用户安装 nvm 后执行同样的命令 node -v装完之后确认版本。Node 20 LTS 是目前稳定性最好的一个版本正好卡在“足够新”和“足够稳”的平衡点上。不建议用 23、24 这类 Current 版本因为某些依赖可能还没跟进兼容。接下来装 Docker。数据库我们直接放到容器里用 Docker Desktop 或者 Linux 上的 docker engine 都行。你可能会问为什么不在本机直接装 PostgreSQL一是因为本机装完会残留一堆服务卸载不干净二是因为用 Docker 可以把数据库环境完全隔离将来你想删掉重建一条命令就搞定。Docker 装完跑个 helloworld 验证docker run --rm hello-world能看到一段欢迎输出就说明 Docker 正常工作。这一步做好了后面拉取 Postgres 镜像就顺理成章。3.3 第二步初始化前端和后端项目基础运行时准备好之后开始创建项目目录。我建议你把你本地的项目目录命名为taskflow后续章节我都沿用这个称呼里面分成两个子包client前端和server后端前后端分离目录天然隔离。先初始化前端mkdir taskflow cd taskflow pnpm create vite client --template react-ts cd client pnpm installVite 的 react-ts 模板会帮你把 React TypeScript 的基础配置全部生成好这比手动配置 Webpack 省出大量时间而且模板配置本身就是社区最佳实践。初始化完成之后跑一下pnpm dev浏览器打开终端提示的地址看到 Vite 默认页面就算成功。再初始化后端。后端目录我们不借助脚手架而是手动搭建这样你能更清楚每一层配置的作用。步骤很简单mkdir server cd server npm init -y pnpm add express4 cors dotenv pnpm add -D typescript ts-node types/node types/express types/cors npx tsc --inittsc --init会生成一个 tsconfig.json里面大部分配置是注释掉的我们需要按项目实际需求调整。这里我直接给出一个能跑的配置{ compilerOptions: { target: ES2020, module: commonjs, rootDir: ./src, outDir: ./dist, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src] }然后创建一个最简入口文件src/index.ts先把服务跑起来确认后端链路没问题。import express from express; const app express(); const PORT Number(process.env.PORT) || 3000; app.use(express.json()); app.get(/api/health, (_req, res) { res.json({ status: ok, timestamp: new Date().toISOString() }); }); app.listen(PORT, () { console.log(Server is running at http://localhost:${PORT}); });这里我加了express.json()中间件来解析 JSON 请求体后续写 POST 接口时是必需品。/api/health是健康检查接口开发阶段很有用部署之后也能用它快速判断服务是否存活。package.json 里的脚本也要改一下把启动命令指向 ts-node方便开发时直接跑 TS 文件scripts: { dev: ts-node src/index.ts, build: tsc, start: node dist/index.js }跑pnpm dev浏览器访问http://localhost:3000/api/health能看到 JSON 响应说明后端开发环境已经通了。到这一步前后端最低限度的“空转”都已经验证完毕。3.4 第三步统一代码规范与 Git 提交基线这一步很多自学者直接跳过但我强烈建议你从第一天就做。代码规范不是为了做给别人看的而是为了让一个月后的你自己还能看懂现在的代码。我通常用 ESLint 检查语法与潜在错误用 Prettier 统一格式两者配合配合方式如下前端 Vite 模板里已经内置了 ESLint我们只需要补一个 Prettiercd client pnpm add -D prettier eslint-config-prettier然后在项目根目录创建.prettierrc文件{ semi: true, singleQuote: true, printWidth: 100, trailingComma: es5 }后端需要从零装 ESLint 和 Prettiercd server pnpm add -D eslint prettier eslint-config-prettier typescript-eslint/parser typescript-eslint/eslint-pluginESLint 的配置文件.eslintrc.cjs我提供一个精简版本module.exports { root: true, parser: typescript-eslint/parser, plugins: [typescript-eslint], extends: [ eslint:recommended, plugin:typescript-eslint/recommended, prettier ], env: { node: true, es2020: true } };再加上统一的.gitignore把node_modules、dist、.env这类文件全部排除掉。.env里将来会放数据库连接串和 JWT 密钥绝不能提交到 Git 仓库。最后初始化 Git打上第一个提交cd taskflow git init git add . git commit -m chore: project bootstrap with client and server这一步做完你的项目就有了一个干净的起点。之后的每一次改动都应该有对应的提交记录这样项目出现问题的时候你可以用git log回看每一步都动了什么定位问题会容易得多。4. 启动阶段高频问题与排查技巧4.1 环境问题速查表我根据带项目的经验把第一章最容易踩的坑整理成一张速查表。如果你启动时报错先对照这里逐项排查问题现象常见原因解决办法nvm命令找不到安装后没有重启终端关闭终端重新打开或执行source ~/.bashrcpnpm无法识别安装完 Node 后未安装 pnpm执行npm install -g pnpmport 3000 is already in use端口被其他进程占用换端口或结束占用进程npx kill-port 3000Vite 启动很慢依赖包未完全安装删掉node_modules和pnpm-lock.yaml重跑pnpm installts-node报ERR_UNKNOWN_FILE_EXTENSIONts-node 与 Node 版本不匹配优先使用 Node 20 LTS或者用tsx替代 ts-nodeDocker 拉取镜像超时网络波动配置镜像加速源或者多尝试几次Git 提交时.env被提交.gitignore 编写不完整检查.gitignore确认包含.env后重新移除缓存这里要特别强调.env的处理。很多新手没把环境变量文件当回事随手就提交了结果数据库密码、密钥全部暴露在仓库里安全隐患极大。记住一个原则凡是以.env结尾的文件一律不进入版本控制。4.2 我踩过的几个坑与心得第一次写这类全栈项目时我犯过一个现在看来很蠢的错误在 Vite 前端里直接写死了后端接口地址。当时看页面一切正常但后来部署到服务器前端页面怎么请求都失败排查了很久才发现是 API 地址写死了 localhost。所以在一开始就要把接口请求地址放到环境变量里开发环境和生产环境分别配置这个系列后续章节我也会持续强调。还有一个关于依赖安装的问题。有些同学执行pnpm create vite client --template react-ts后发现项目里没有node_modules于是手动又装了一遍依赖结果版本冲突。其实pnpm create生成的模板不会自动装包执行完pnpm install之后才能跑起来。这个流程本身不复杂但很多第一次用模板的人都栽在这一步。再有一个经验是关于“跟着教程跑通了但不知道自己做了什么”的。我会建议你在每个章节结束之后自己把项目从头到尾重新初始化一遍。第一次照着抄第二次凭记忆写第三次不看任何参考自己搭。这个过程很枯燥但效果非常明显。说白了搭环境的肌肉记忆本身就是一种能力它能保证你将来接手新项目时不会被工具链吓退。5. 第一天就完成这个小目标第一章的内容到这里你已经完成了整个系列最“朴素”但最重要的一部分理解了课程的全貌确认了技术选型并且把前后端开发环境从零跑通了。我的建议是在第一天的收尾阶段不要急着学新东西。你把项目跑起来然后改一行界面文案再往后端加一个接口比如在/api/health里多加一个字段res.json({ status: ok, timestamp: new Date().toISOString(), version: 0.1.0 });重新访问页面看到变化提交一次 Git关电脑。这就够了。第一天不一定要学多少新知识点但这种“改代码—看到效果—提交提交”的正向反馈比任何督促都管用它能帮你保留对项目的热情。根据我个人经验很多人真正放弃一个项目不是因为它有多难而是开头几步太琐碎、太受挫今天装环境失败明天装依赖报错连续几天没有正向反馈就放弃了。所以第一章刻意把任务量控制得很小目标只有一个让你拥有一台能开发前后端项目的机器以及一个跑得起来的空项目。下一章我会直接从数据库表结构开始把用户、项目、任务这三张核心表建出来然后打通第一个注册接口。