简介苍穹外卖前端环境搭建笔记面向正在学习或开发苍穹外卖项目的开发者聚焦前端启动环节中高频出现的 Nginx 启动失败问题。文档以真实报错为切入点指出即使未改动任何配置仅双击 nginx.exe 也可能因安装目录含中文、系统无法自动创建 temp/client_body_temp 子目录而无法访问服务并分步给出将 Nginx 移至纯英文路径、手动新建缺失目录、检查端口占用与防火墙等解决办法同时补充 nginx.conf 中监听端口、server blocks 等关键配置项的说明便于后续部署举一反三。资源为 1 个 docx 格式文档压缩包约 100KB按问题描述、报错信息、解决步骤和扩展说明的结构整理可直接对照操作。已有 3697 人学习下载适合遇到同类前端环境问题的读者快速定位原因并完成修复。1. 为什么“苍穹外卖”这类项目前端环境搭建比写代码更劝退打开一个名叫“苍穹外卖”的外卖项目前端时第一道坎从来不是登录页怎么写而是npm run dev之后终端抛出一长串红色报错页面白屏或者依赖装到一半就中断。我见过不少同学拿到项目第一天后端接口都通了前端还卡在环境上一卡就是一整天。这题真正的难点不是装软件而是版本匹配Node 版本、包管理器、脚手架工具、依赖锁版本一个不对就翻车。这篇内容就按我平时给项目搭前端环境的顺序来拆先讲怎么判断项目需要什么环境再落到安装、启动、联调的具体命令最后把常见的踩坑记录按“现象 → 原因 → 解决”列出来。适合刚拿到项目还没跑通的初学者也适合给团队搭统一开发环境的人做参考。2. 动手前先看懂依赖环境搭建的版本选型逻辑前端环境搭建最忌讳的就是拿到项目直接npm install。你根本不知道这个项目的依赖体系是什么盲目执行只是在赌运气。正确顺序是先读项目结构再决定装什么版本的工具链。这一章把选型逻辑讲透你后面每一步才走得稳。2.1 先读 package.json判断脚手架与依赖体系项目根目录下的package.json是整个前端环境的“说明书”。打开它先看三处dependencies和devDependencies里的框架名、scripts里的启动命令、engines字段如果有的话。框架名决定你用哪套开发服务器scripts决定你该跑哪个命令engines直接告诉你作者建议的 Node 版本范围。# 进入项目目录后用 cat 直接看关键字段 cat package.json | head -50# 只看 scripts 和 dependencies更聚焦 npm pkg get scripts dependencies devDependencies第二条命令比第一条更实用。它直接输出scripts和两处依赖清单你不用在一大堆 JSON 里翻。如果dependencies里出现vue那这就是 Vue 项目如果出现react那就是 React 项目。外卖类前端项目我遇到的以 Vue 居多但这不是定论一切以你手里的package.json为准。scripts字段是重中之重。常见的外卖项目前端会写dev: vite或serve: vue-cli-service serve。你后面启动命令应该跑npm run dev还是npm run serve完全由这里决定。很多人习惯性跑npm run dev结果项目只有serve脚本报错missing script: dev这就很尴尬。2.2 Node.js 版本怎么选不纠结原理只看匹配Node 版本是前端环境里最容易出问题的变量。老项目用 webpack4 node-sass 的话Node 16 以上基本装不上node-sass新项目用 Vite 的话Node 18 以下又跑不起来。所以选 Node 版本不是选最新而是选“项目依赖能兼容”的版本。项目里有node-sass优先考虑 Node 14 或 16配 npm 6 或 8项目用 Vite 和简单依赖Node 18 或 20 LTS 版本基本通吃package.json里有engines字段以它为准不要用别的版本# 查看当前 Node 和 npm 版本确认自己现在的基线 node -v npm -v如果版本不对不建议你卸载重装更推荐用 nvmNode Version Manager这类工具切换。nvm 允许你在同一台机器上装多个 Node 版本随时切换。我一般会保留一个 Node 16 和一个 Node 20老项目用前者新项目用后者互不干扰。2.3 包管理器选哪个npm、yarn 还是 pnpm外卖类前端项目里最常见的是 npm这是最稳妥的选择。yarn 和 pnpm 各有优势但前提是项目里有对应的yarn.lock或pnpm-lock.yaml文件。如果没有锁文件强行用 pnpm 安装依赖树解析方式不一致可能装出和作者不一致的版本。我的习惯是项目根目录有package-lock.json就用 npm有yarn.lock就用 yarn有pnpm-lock.yaml就用 pnpm。锁文件存在意味着依赖版本被固定你只要按对应工具安装理论上不会出现版本漂移问题。# 判断该用哪个包管理器看锁文件 ls -la | grep -E package-lock.json|yarn.lock|pnpm-lock.yaml这里说一个很多人忽视的点即使你决定用 npm也别急着全局升级到最新版。npm 9 和 npm 10 在某些老项目上会有 peer dependency 解析差异导致npm install报ERESOLVE错误。遇到这种错解决方案不是换源而是npm install --legacy-peer-deps让 npm 沿用旧的依赖解析逻辑。这个参数后面避坑章节还会再提。2.4 脚手架工具的隐含选择Vue CLI 与 Vite 的差异同样是 Vue 项目Vue CLI 和 Vite 的启动逻辑差别很大。Vue CLI 基于 webpack启动慢、依赖重但兼容性好Vite 基于 esbuild启动快但对 Node 版本有硬性要求。判断方法很简单看package.json里有没有vue/cli-service有就是 Vue CLI有没有vite有就是 Vite。这两种脚手架对环境的敏感度完全不同。Vue CLI 项目在 Node 18 上经常报 OpenSSL 相关的digital envelope routines::unsupported错误因为 webpack 4 用的哈希算法在新版 Node 里不再支持。Vite 项目则很少遇到这种问题但要求 Node 版本不能太低。你不需要把两者的原理背下来只需要知道拿到项目先看脚手架类型再决定 Node 版本这个过程能省下大量排错时间。3. 把依赖装进本地从零跑通前端的最小命令链环境选型确定后接下来就是真正的安装过程。这一章给出最小可选命令链每一步拆开讲清楚顺带说明失败时的排查方向。3.1 最小安装命令三步走# 第一步进入项目根目录把路径换成你自己的 cd ~/work/sky-takeout-frontend # 第二步安装依赖根据锁文件选择包管理器 npm install # 第三步启动开发服务器脚本名以 package.json 为准 npm run dev这三条命令是环境搭建的核心闭环。第一步是路径问题很多人卡在“在错误的目录里执行了 npm install”装完发现项目根目录多了个 node_modules但实际依赖一个都没装上。第二步是依赖解析网络和版本都会在这一步暴露问题。第三步是最终验证能启动成功说明环境基本通了。依赖装完先看一眼# 确认 node_modules 存在且目录里有 .bin 目录 ls -la node_modules/.bin | head -20.bin目录里存放的是项目本地命令的可执行文件。如果这个目录没生成说明依赖没装完整即使npm install显示成功启动时也可能报command not found。3.2 npm install 失败的三个原因与处理顺序安装失败时不要急着换源先看报错类型。我遇到过的绝大多数失败可以归成三类第一类是网络层错误报ETIMEDOUT、ECONNRESET或者卡在某个包下载不动。这种处理方式是换 registry 镜像国内一般换到官方镜像地址。但注意换镜像后如果之前已经有部分依赖装好了要先删掉node_modules和锁文件再重装否则容易残留半成品依赖。第二类是版本解析错误报ERESOLVE或peer dep conflict。这类错误多半是某个依赖要求特定版本的另一个包而你锁文件里的版本对不上。解决办法是npm install --legacy-peer-deps跳过严格的对等依赖检查。这不是一个“优雅”的解法但非常有效特别是老项目。第三类是编译错误报node-gyp相关的信息说明某个依赖需要本地编译。外卖类项目里最常见的触发者是node-sass它需要 Python 和 C 编译环境或者需要对应的 Node 版本。这种没有捷径确认有编译环境后可以考虑把node-sass换成sassdart-sass。这个替换是官方推荐的且接口兼容。# 网络原因时临时换镜像源只对本次生效 npm install --registryhttps://registry.npmmirror.com # 版本冲突时跳过 peer dependency 严格校验 npm install --legacy-peer-deps两条命令不是同时用根据报错类型选一条。我见过不少人在网络正常时也强行换源反而装到 half-finished 的依赖包得不偿失。3.3 启动命令的差别dev 与 serve 不是同一个东西npm run dev是个约定俗成的名字但项目里到底跑哪个以scripts为准。外卖类前端项目里常见两种dev: vite跑 Vite 开发服务器默认端口 5173serve: vue-cli-service serve跑 Vue CLI 开发服务器默认端口 8080# 不确定脚本名时直接列出全部 scripts npm runnpm run不带参数会把所有可用脚本列出来。看到列表你就知道该项目能跑哪些命令了。如果列出来只有serve没有dev那就老老实实跑npm run serve。启动成功后终端会显示本地访问地址常见格式是http://localhost:8080/或http://127.0.0.1:5173/。如果终端显示Network: http://192.168.x.x:8080/那个是用局域网 IP 访问的地址你手机连同一个 Wi-Fi 也可以打开但本机调试时用 localhost 就行别在局域网地址上纠结。3.4 启动失败的排查顺序端口、白屏、报错启动失败时按顺序检查三处。第一端口是否被占。报EADDRINUSE或Port 8080 is already in use说明端口被别的进程占用找到并结束它或者改端口。第二编译是否报错。Vite 或 webpack 会把语法错误、模块缺失直接抛在终端定位到具体文件去修。第三页面是否白屏不报错。这种情况最头疼因为终端无异常但页面空荡荡多半是入口挂载点问题或路由模式问题这个具体到项目代码不是环境问题。# 排查端口占用找出占用 8080 的进程 lsof -i :8080 # 找到 PID 后杀掉Linux 和 macOS 通用 kill -9 PIDWindows 系统没有lsof用netstat -ano | findstr :8080然后taskkill /PID PID /F。这个细节区分一下免得在系统命令上报错。4. 让前端和后端对上话联调代理与环境变量的配置参数前端页面能打开只是第一步。外卖项目的前端一定需要请求后端接口如果前后端是分离部署的就必然碰到跨域和接口地址配置问题。这一章讲 devServer 代理和.env环境变量文件这两个是环境搭建里最容易被遗漏的环节。4.1 devServer 的 proxy 配置跨域不是前端 CORS 的锅开发环境里前端跑在http://localhost:8080后端跑在http://localhost:8081前端直接发请求到http://localhost:8081/api/xxx一定会有跨域问题。解决方式不是在后端加Access-Control-Allow-Origin而是在前端 devServer 里配置代理。让前端请求一个同源地址devServer 把这个请求转发到后端真实地址。Vue CLI 项目在vue.config.js里配置Vite 项目在vite.config.js里配置两者写法略有差异// vue.config.js 里的写法Vue CLI 项目 module.exports { devServer: { port: 8080, proxy: { /api: { target: http://localhost:8081, // 后端服务地址 changeOrigin: true // 让后端认为请求来自同源 } } } }// vite.config.js 里的写法Vite 项目 export default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8081, changeOrigin: true } } } })两个写法核心一致。/api意思是前端所有以/api开头的请求都会转发到target指定的地址但浏览器地址栏里看到的还是http://localhost:8080/api/xxx所以不会触发跨域。changeOrigin: true这个参数很关键它会让 devServer 在转发请求时把请求头里的Host字段改成后端地址否则有些后端会拒绝请求。有两点要注意一是代理只在 devServer 阶段生效生产环境构建后不经过 devServer代理逻辑不生效二是修改vue.config.js或vite.config.js后需要重启 devServer 才生效热更新只针对源码文件不涵盖配置文件。4.2 环境变量文件前端也要有“配置中心”外卖类项目前端一般会有多个环境本地开发、测试环境、生产环境。不同环境的后端接口地址不同不能每次手动改代码。.env文件就是前端的配置中心它允许你按环境加载不同变量。# 项目根目录下常见的环境变量文件 .env.development # 开发环境npm run dev 时加载 .env.production # 生产环境npm run build 时加载# .env.development 内容示例 VITE_BASE_URL/api VITE_TIMEOUT10000# .env.production 内容示例 VITE_BASE_URLhttps://api.example.com VITE_TIMEOUT30000VITE_前缀是 Vite 项目的要求只有带这个前缀的变量才会被暴露给前端代码。Vue CLI 项目对应的是VUE_APP_前缀。前缀不对变量取不到undefined。在代码里读取方式// Vite 项目里读取环境变量 const baseURL import.meta.env.VITE_BASE_URL// Vue CLI 项目里读取环境变量 const baseURL process.env.VUE_APP_BASE_URL环境变量的好处是你不用在代码里写死接口地址。切环境时只换.env文件内容不碰源码。但注意修改.env文件后同样需要重启 devServer某些项目对import.meta.env的解析是启动时确定的不会热更新。4.3 网络请求封装不要把 baseURL 写死在业务代码里常见做法是把 baseURL 提取到 request 封装层业务代码只写/api/xxx这样的相对路径。好处是换环境时不用全局搜索替换。很多外卖项目前端都会用 axios 封装一个 request 实例baseURL 从环境变量读取。// request.js 封装层示例Vite 项目 import axios from axios const request axios.create({ baseURL: import.meta.env.VITE_BASE_URL, timeout: import.meta.env.VITE_TIMEOUT || 10000 }) export default request// 业务代码里直接用相对路径 import request from ./request request.get(/order/list).then(res { console.log(res.data) })加timeout参数是为避免请求挂死。外卖类项目如果后端接口没有及时响应请求会一直 pending页面看起来像卡住了超时设置能快速暴露问题。这个细节很多人忽略接口慢到一个阈值才想起来调不如一开始就配好。5. 前端环境搭建常见问题与避坑5条具体的翻车记录环境搭建的坑往往不在“大方向”而在“小细节”。这一章记录 5 条高频问题按现象 → 原因 → 解决的结构来写全是实际踩过的。5.1 node-sass 安装失败报错一串编译信息现象npm install执行到node-sass时卡住然后报gyp ERR! stack Error: not found: python2或者Module build failed: Error: Node Sass does not yet support your current environment。原因node-sass是一个依赖本地编译的包它需要 Python 2/3、C 编译工具链并且对 Node 版本极敏感。Node 版本和node-sass版本不匹配时它宁可报错也不给你编译。解决优先考虑替换为sassdart-sass这是官方推荐的后继者API 和node-sass完全兼容。在项目根目录执行# 先卸载 node-sass再安装 sass npm uninstall node-sass npm install -D sass1.x安装完重新启动 devServer样式编译就能跑通。如果项目里还是依赖node-sass的某些特殊功能退而求其次是用相配的 Node 版本比如node-sass4.14配合 Node 14。5.2 启动时报错 digital envelope routines::unsupported现象Vue CLI 项目在 Node 18 上执行npm run serve终端报error:0308010C:digital envelope routines::unsupported页面无法启动。原因webpack 4 使用了 Node 17 之后被禁用的哈希算法OpenSSL 3.0导致构建失败。这是典型的版本兼容问题不是你的代码有问题。解决两个方向推荐第一个。第一个是给启动命令加NODE_OPTIONS--openssl-legacy-provider环境变量让 Node 启用旧的 OpenSSL 提供者# Linux / macOS NODE_OPTIONS--openssl-legacy-provider npm run serve # Windows cmd set NODE_OPTIONS--openssl-legacy-provider npm run serve第二个是降级 Node 到 16用 nvm 切换即可。实际派系第一种方式适合临时救急第二种方式适合长期开发。如果你要长期维护老项目建议直接固定在 Node 16别每次启动都拿环境变量去赌。5.3 依赖装无数次启动还是报 Module not found现象npm install执行成功且没有报错但启动时报Module not found: Cant resolve xxx。原因依赖树不完整。最常见的是npm install中断过或者你用了不同包管理器在同一个项目里交叉安装导致部分依赖没有解析出来。解决彻底重装。这一步要做的不仅是删node_modules而是连锁文件一起处理# 备份后删除依赖和锁文件 rm -rf node_modules package-lock.json npm install如果项目里有多余的yarn.lock或pnpm-lock.yaml也一并删除避免 npm install 时按别的锁文件解析。重装后启动基本能解决这类问题。5.4 页面能打开但所有接口请求 404 或跨域报错现象前端页面正常显示但打开控制台所有请求都是红色 404或者直接报 CORS 错误接口一个都通不了。原因大概率是 devServer proxy 配置没生效。常见原因有三个修改代理配置后没重启 devServer代理路径写错比如请求是/api/order/list代理却只对/order开头的路径生效后端服务端口和target不一致。解决确认三处是对的——后端服务地址代理路径前缀以及 devServer 是否是重启后的最新配置。改完配置后养成重新启动的习惯不要指望热更新。另外可以在浏览器控制台手动测一个请求确认转发有没有生效curl http://localhost:8080/api/health如果返回的是后端数据说明代理生效如果返回index.html的内容说明请求没被代理接管去查路径前缀的匹配规则。5.5 启动成功但页面空白终端也没有报错现象npm run dev正常执行终端没有报错浏览器打开http://localhost:5173白屏控制台也无报错。检查源码发现根目录有代码但页面不渲染。原因这种情况少见但一旦遇到很折磨人。常见原因是入口 HTML 文件的挂载节点找不到或者路由 mode 设置导致刷新时路径无法解析。外卖类项目常用history路由模式本地开发时直接访问二级路径会 404但白屏且无报错的情况可能与挂载有关。解决看index.html里的挂载节点是不是idapp再看入口文件创建的 Vue 实例是否挂载到#app。路由模式如果是history开发环境可以在 devServer 里配置historyApiFallback: true让所有路径都回退到index.html// vite.config.js 里配置 export default defineConfig({ historyApiFallback: true })如果这一步不生效优先切换成hash路由模式试一下虽然地址栏会多个#但至少页面能跑起来不影响开发效率。6. 最后一步验证你的环境是“能开发的”而不是“能显示的”环境搭建完成的标志不是页面能打开而是你改一行代码能看到效果。很多人的环境停留在“能显示”的状态就以为自己配好了结果改代码不生效或者接口一调就炸。这一章给出一个验证清单和收尾技巧。6.1 环境健康检查一条命令确认基线# 确认 Node、npm、脚手架版本基线 node -v npm -v# 检查本地依赖是否完整无红黄警告 npm ls --depth0npm ls --depth0会列出项目直接依赖的版本和状态。输出里有invalid或UNMET DEPENDENCY说明有这个包但版本不对或没装全需要单独处理。全绿无异常说明依赖层是健康的。6.2 改动验证热更新到位才算环境通了打开页面随便改一个页面文件里的文字内容比如把首页标题改成hello保存后浏览器页面应该自动刷新并显示新内容。如果在 3 秒内没有刷新检查 devServer 终端有没有输出hmr update或者page reload。没输出说明热更新被关掉或配置不对这个比看到页面更有意义——它验证的是开发循环闭环。6.3 我这边的习惯项目环境记录成文件每次给新项目配完环境我会在项目根目录写一个SETUP.md记录三件事Node 版本、包管理器、启动命令。这个文件后续任何人接手项目都能少踩坑。我发现很多人配完环境就跑下一个同事拿到项目又从头开始试错这其实是一种隐形损耗。记下来不仅帮别人回头看也知道自己当初怎么配的。前端环境搭建难就难在它不是一个持续写的代码问题而是版本、工具链和配置之间的各种隐性耦合。上面这些细节都是我在真实项目里反复踩过的希望帮到你。本文还有配套的精品资源点击获取