本系列用一个“任务看板”贯穿环境、组件、路由、状态、数据、样式、表单、性能、测试与交付。第一篇不急着画页面而是先建立可复制的工程基线同一份源码在成员电脑与 CI 中得到相同依赖、相同检查结果和可追踪构建物。一、痛点能启动不等于能协作前端项目常从一条脚手架命令开始却在第二位开发者加入后暴露问题Node 版本不同、锁文件被忽略、编辑器各自格式化、环境变量混入客户端包。真正的环境搭建要回答四个问题运行时版本如何固定依赖如何确定质量门禁如何一键执行秘密如何与公开配置分离。推荐选当前受支持的 Node.js LTS并在.nvmrc或.node-version写明精确版本仓库只保留一种包管理器及其锁文件。package.json的packageManager字段还能约束 pnpm/npm 版本。CI 使用冻结锁文件安装例如pnpm install --frozen-lockfile这样锁文件与清单不一致会直接失败而不是悄悄解析出另一棵依赖树。这里的关键不是团队必须使用同一款编辑器而是所有会影响产物的输入都进入仓库。Node 版本、包管理器版本、锁文件、编译选项和环境变量结构都属于构建输入字体大小、主题颜色等个人偏好则不是。可以把这条判断迁移到任何框架凡是“换一台机器后可能改变检查结果”的设置都应由项目脚本或配置文件接管。README 只解释入口机器可执行的约束才是真正契约。任务看板采用 TypeScript、React 与 Vite 起步。命令可写成npm create vitelatest task-board -- --template react-ts然后把dev、build、lint、test、typecheck作为统一入口。不要让 CI 内藏一套开发者无法本地复现的命令npm run typecheck应明确执行tsc --noEmit构建负责产物类型检查负责契约两者失败含义不同。二、原理确定性来自显式输入语义化版本范围描述“允许更新什么”锁文件记录“本次实际安装什么”。两者缺一不可只提交清单会随时间漂移只提交锁文件却不审查清单会掩盖升级意图。下面的可执行程序用依赖约束与锁定版本模拟冻结安装并在偏差出现时给出可行动错误。fromdataclassesimportdataclassdataclass(frozenTrue)classDependency:name:strwanted_major:intmanifest[Dependency(react,19),Dependency(vite,7),Dependency(typescript,5),]lockfile{react:19.1.1,vite:7.1.1,typescript:5.9.2,}deffrozen_install(items,locked):installed[]foriteminitems:versionlocked.get(item.name)ifversionisNone:raiseValueError(fmissing lock:{item.name})majorint(version.split(.)[0])ifmajor!item.wanted_major:raiseValueError(fmajor mismatch:{item.name})installed.append(f{item.name}{version})returninstalledforpackageinfrozen_install(manifest,lockfile):print(package)运行输出react19.1.1 vite7.1.1 typescript5.9.2三、实现把环境做成契约目录按职责拆成src/components、src/features、src/lib与src/test。业务功能放在 feature 内通用基础设施才进入 lib这比按“所有 hooks 一个目录、所有 types 一个目录”更能限制跨功能耦合。开启 TypeScript 的严格模式别用大量as绕过错误。ESLint 负责潜在缺陷Prettier 只负责排版避免两套规则争夺同一职责。环境变量必须有边界。Vite 中带VITE_前缀的值会进入浏览器因而只能放公开配置数据库口令、签名密钥永远不应出现。提交.env.example只列名称与安全示例不提交真实.env.local。在应用启动时校验变量错误应尽早发生而不是用户点到某页面才得到undefined。建议再建立一个单一门禁命令例如check依次执行格式检查、lint、类型检查和单元测试CI 随后单独执行生产构建。顺序有实际意义便宜且反馈明确的检查先失败昂贵构建后运行但每个子命令仍可独立调用便于定位。开发服务器能热更新并不证明生产构建成立生产构建成功也不证明类型和行为正确所以不要用一个命令的成功替代另一类证据。目录同样应有导入规则。features/tasks可以依赖components/ui与lib/http通用层却不能反向引用任务业务。这样未来把任务模块迁到另一套路由、把 HTTP 实现换成服务端动作时改动会停留在边界内。若项目暂时很小不必先上自动化架构检查但应在代码审查中保持这个方向模块增多后再用 ESLint 边界规则固化。fromdataclassesimportdataclassdataclass(frozenTrue)classRule:name:strpublic:boolrequired:boolTruerules[Rule(VITE_API_BASE,True),Rule(VITE_RELEASE,True),Rule(DATABASE_URL,False),]values{VITE_API_BASE:https://api.example.test,VITE_RELEASE:local,DATABASE_URL:postgres://server-only,}defclient_config(schema,source):result{}forruleinschema:valuesource.get(rule.name,).strip()ifrule.requiredandnotvalue:raiseValueError(fmissing{rule.name})ifrule.public:result[rule.name]valuereturnresult configclient_config(rules,values)print(sorted(config))print(secret_exposed,DATABASE_URLinconfig)print(api,config[VITE_API_BASE])运行输出[VITE_API_BASE, VITE_RELEASE] secret_exposed False api https://api.example.test四、踩坑工具越多不代表基线越强第一天就引入 monorepo、微前端和复杂提交钩子通常只会放大认知成本。先让格式、静态检查、类型检查、单元测试和生产构建稳定运行再按真实瓶颈扩展。提交钩子适合快速检查改动文件完整检查仍应在 CI 执行否则开发者跳过钩子后门禁就消失。还要避免把“最新”误当成“可复现”。依赖机器人可以提出升级但升级应作为有意变更附带锁文件差异、变更说明和回归结果。若某个原生依赖在不同操作系统生成不同结果CI 至少覆盖团队支持的系统或将工具链放入固定镜像。固定版本不是永不升级而是把升级从偶然事件变成可审查事件。不要把.env.example写成假秘密仓库也不要认为前端变量经过打包后“看不见”。浏览器下载的 JavaScript 对用户完全可读。另一个常见误区是全局安装 CLI项目脚本应调用本地依赖确保版本跟仓库走。升级依赖时单独提交锁文件变化阅读 release notes并运行全部门禁。五、验证新成员十分钟验收在一台没有全局前端工具的环境克隆仓库只依据 README 完成安装、开发服务器、测试与构建。删除node_modules后再次冻结安装检查没有未提交变化故意删掉必要环境变量确认启动立即给出字段名把清单主版本改错确认安装失败。记录 Node 与包管理器版本、构建耗时和产物大小作为后续优化基线。最后做一次“污染检查”搜索构建目录是否出现测试域名、服务器密钥名称或本机绝对路径用全新目录安装确认脚本没有依赖未声明的全局命令在 CI 保存构建摘要和依赖审计结果。迁移到 Vue、Svelte 或别的构建器时工具名会变化但验收问题不变输入是否显式、安装是否确定、公开配置是否可识别、门禁是否能在任意机器复现。掌握这四点环境搭建就从脚手架操作变成可移植的工程方法。至此我们得到的不是一个“能跑的模板”而是一份版本、依赖、配置和门禁都显式化的协作契约。下一篇将在这条基线上实现任务列表讲清组件边界、状态快照、Effect 的适用范围与可复用 Hook。参考来源Node.js发布计划Vite开始使用TypeScriptTSConfig strict 觉得有用就点个赞 收藏方便回头查阅有疑问直接在评论区留言我看到都会回。 本文属于《现代前端框架实战》系列持续更新关注不迷路。 文章里的代码都能直接跑。想要可直接 clone 的完整工程 配套部署脚本 / 踩坑清单评论一声或发邮件到cj2664qq.com我免费发你。如果你正好在做类似系统、或有工程化难题想找人做也欢迎邮件聊一句——我按实际情况评估能落地的就接单或出方案。评论和邮件都能直接找到我不用跳别的平台。