前端项目本地环境的可复现搭建“在我电脑上能跑”通常说明环境里有未被记录的前提。Node.js 版本、包管理器、系统依赖、代理配置和本地服务只要有一项靠口头传递新成员或 CI 就可能得到不同结果。可复现搭建的目标不是承诺几分钟内启动而是让失败发生在明确步骤并给出可以继续排查的信息。开始之前先确定本地开发的最小范围。若当前只修改组件不必强制启动全部后端若要联调登录或支付就要说明哪些依赖不能用 mock。把“编辑一个页面需要什么”与“完整还原整套系统需要什么”分开搭建说明会清楚很多。工具链版本由仓库声明Node.js 和包管理器版本应写进仓库而不是只写在聊天记录里。可以使用.nvmrc、.node-version或项目现有的版本管理工具固定 Node.js在package.json中声明packageManager和engines。安装命令启动前先检查版本不符合就直接提示。锁文件必须进入版本管理CI 使用冻结锁文件的安装方式。遇到依赖问题时不要先删除锁文件重新解析先确认当前 Node、pnpm 与平台是否在支持范围。包含原生扩展的包还要记录系统库和编译工具要求错误日志中保留失败包与构建阶段。Monorepo 的工作区范围保持简单即可packages: - apps/* - packages/* - !**/fixtures/**这份配置只定义哪些目录属于工作区不会自动保证原生模块只构建一次也不会解决 React 多实例。依赖关系仍应在各包的package.json中正确声明公共库将 React 放在合适的 peer dependency 位置再由应用提供具体版本。先用默认解析规则再补必要配置为了解决本地问题而堆叠 Vite alias、预构建列表和文件监听例外常常会制造新的环境差异。先让工作区包通过标准导出和 TypeScript 项目配置被识别只有能稳定复现某个解析问题时才增加特例。React 出现重复实例时可以先检查依赖树确认是内部包错误声明了普通依赖还是链接方式造成解析偏差。resolve.dedupe可以作为应用侧防线但不能替代修正包的依赖声明。直接把 React alias 到某个固定node_modules路径在不同工作区布局下很脆弱。import { defineConfig, loadEnv } from vite; import react from vitejs/plugin-react; export default defineConfig(({ mode }) { const env loadEnv(mode, process.cwd(), DEV_); return { plugins: [react()], resolve: { dedupe: [react, react-dom], }, server: { host: env.DEV_LISTEN_ALL true ? 0.0.0.0 : 127.0.0.1, port: 5173, strictPort: true, proxy: env.DEV_API_ORIGIN ? { /api: { target: env.DEV_API_ORIGIN, changeOrigin: true, }, } : undefined, }, }; });示例默认只监听回环地址。容器或远程开发确实需要对外监听时再通过显式开关启用并确认宿主防火墙和鉴权。代理目标使用本地公开配置不把内部令牌写进 Vite 环境变量因为进入前端构建的值无法保密。HMR 是否能观察到工作区包变化要结合包是直接引用源码还是引用构建产物。前者需要 Vite 与 TypeScript 解析到同一路径后者需要子包 watch 任务稳定生成文件。不要两种方式同时存在否则编辑器、测试和浏览器可能分别加载不同版本。Mock 与真实接口应使用同一份契约MSW 可以在浏览器端拦截请求Node 测试也能使用对应处理器但两端生命周期不同。处理器应共享请求与响应 Schema启动方式则分别配置。浏览器未注册 Service Worker 时页面要给出清楚提示测试进程结束后Node 端拦截器要恢复环境。Mock 数据使用虚构内容并覆盖正常、空数据、权限拒绝和服务错误。它不应永远返回理想结果。切换到真实接口时只替换传输目标不改变组件消费的数据结构。若 staging 与本地 mock 的契约不同应优先修契约或 mock而不是在页面里增加环境分支。开发容器是选项不是唯一入口Dev Container 可以固定操作系统和工具链尤其适合依赖原生库的项目但它也带来镜像下载、文件性能和端口映射问题。团队可以同时提供容器与本机方案只要两者调用同一组仓库命令并通过相同自检。{ name: frontend-workspace, image: mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm, postCreateCommand: corepack enable pnpm install --frozen-lockfile, forwardPorts: [5173] }容器镜像版本需要定期更新并验证不要默认加入 Docker-in-Docker、云凭据或额外权限。只有项目确实需要启动容器化依赖时再选择合适方案。编辑器扩展属于体验建议不应成为构建成功的隐藏条件。从空目录验证整条路径搭建说明至少包含获取代码、检查版本、安装依赖、准备示例配置、启动最小服务、运行健康检查以及停止和清理。用一个全新的目录执行能发现本机缓存、全局命令和未提交文件带来的假成功。启动后验证一次页面加载、一次 mock 错误和一次修改后的 HMR。再停止所有进程并重新启动确认端口、缓存和临时文件没有残留。出现问题时记录命令、工具版本和第一处失败不收集环境变量全文或个人目录。可复现环境不等于所有机器速度相同也不保证外部权限自动具备。它提供的是一条可检查的路径每一步有什么输入成功后得到什么失败时去哪里找原因。只要这条路径由仓库持续验证本地搭建就不会再依赖某位同事记得全部细节。