企业官网建设流程全解析

本系列用一个“任务看板”贯穿环境、组件、路由、状态、数据、样式、表单、性能、测试与交付。第一篇不急着画页面，而是先建立可复制的工程基线：同一份源码在成员电脑与 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 vite@latest task-board -- --template react-ts，然后把dev、build、lint、test、typecheck作为统一入口。不要让 CI 内藏一套开发者无法本地复现的命令；npm run typecheck应明确执行tsc --noEmit，构建负责产物，类型检查负责契约，两者失败含义不同。

二、原理：确定性来自显式输入

语义化版本范围描述“允许更新什么”，锁文件记录“本次实际安装什么”。两者缺一不可：只提交清单会随时间漂移，只提交锁文件却不审查清单会掩盖升级意图。下面的可执行程序用依赖约束与锁定版本模拟冻结安装，并在偏差出现时给出可行动错误。

fromdataclassesimportdataclass@dataclass(frozen=True)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:version=locked.get(item.name)ifversionisNone:raiseValueError(f"missing lock:{item.name}")major=int(version.split(".")[0])ifmajor!=item.wanted_major:raiseValueError(f"major mismatch:{item.name}")installed.append(f"{item.name}@{version}")returninstalledforpackageinfrozen_install(manifest,lockfile):print(package)

运行输出：

react@19.1.1 vite@7.1.1 typescript@5.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 边界规则固化。

fromdataclassesimportdataclass@dataclass(frozen=True)classRule:name:strpublic:boolrequired:bool=Truerules=[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:value=source.get(rule.name,"").strip()ifrule.requiredandnotvalue:raiseValueError(f"missing{rule.name}")ifrule.public:result[rule.name]=valuereturnresult config=client_config(rules,values)print(sorted(config))print("secret_exposed=","DATABASE_URL"inconfig)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：开始使用
• TypeScript：TSConfig strict

👍 觉得有用就点个赞 + 收藏，方便回头查阅；有疑问直接在评论区留言，我看到都会回。

🚀 本文属于《现代前端框架实战》系列，持续更新，关注不迷路。

📌 文章里的代码都能直接跑。想要可直接 clone 的完整工程 + 配套部署脚本 / 踩坑清单？评论一声或发邮件到cj2664@qq.com，我免费发你。
如果你正好在做类似系统、或有工程化难题想找人做，也欢迎邮件聊一句——我按实际情况评估，能落地的就接单或出方案。评论和邮件都能直接找到我，不用跳别的平台。