简介面向苍穹外卖项目前端环境搭建的初学者与开发人员这份文档聚焦本地服务启动阶段的常见障碍尤其围绕 Nginx 无法正常访问时的排查与处理展开。压缩包共 1 个 docx 文件大小约 100KB体量轻便适合随项目资料归档、课程实训时随时查阅。文档从启动失败现象与 error.log 错误信息入手分析中文路径导致的目录创建异常、temp 与 client_body_temp 目录缺失等问题并延伸到 nginx.conf 配置检查、防火墙设置、端口占用检测等排错方向帮助读者理解路径规范、目录结构与启动流程形成从日志定位到环境修复的完整思路。已有 3698 人学习适合希望快速掌握前端环境搭建要点、减少重复踩坑成本的开发者参考对于刚接触苍穹外卖项目、需要独立完成前端运行环境准备的同学尤其友好。1. 环境先摆清楚苍穹外卖前端真正卡住你的不是 npm install苍穹外卖的前端环境搭建十个人里有八个以为把代码拉下来、npm install跑完、开发服务器起来就算完事。真到要交付、要把管理端和用户端 H5 挂到 Nginx 上模拟线上环境那天才会遇到一连串麻烦页面白屏、刷新就 404、接口全 502。这时候才发现卡住的从来不是前端代码而是 Node 版本、Nginx 目录、代理转发这三件不起眼的小事。我遇到过最典型的一次翻车配置文件一个字没动只是双击了nginx.exe浏览器死活打不开error.log里只留下一行CreateDirectory() ... failed (3: The system cannot find the path specified)。这套环境适合两类人要在家把项目完整跑起来的前端同学以及要拿 Nginx 预演一遍部署流程的交付同学。下面按装什么、怎么装、坏了怎么救的顺序把这条路走一遍。2. Node.js 与 npm 落地版本对齐、路径干净、镜像可用前端环境的第一块地基是 Node。这块地基不稳后面所有问题都会以奇怪的形式冒出来装依赖报gyp编译错误、npm run dev起不来、打包产物跟别人不一样。这一章不讲 Node 是什么只讲怎么把它装成一套能长期用、换项目不用重装的样子。2.1 版本怎么定先看 lock 文件和工程要求别上来就装最新版新手最容易犯的错是去官网下最新 LTS装完发现npm install报一堆原生模块编译失败。原因很简单前端工程里的package-lock.json是上一个开发者用某个 Node 版本生成的锁文件里记录了当时所有依赖的解析结果Node 大版本一变npm 的解析规则和部分包的原生二进制就可能对不上。所以进工程根目录的第一件事不是装依赖是先看清楚要求。# 进入前端工程根目录先看这几处再决定装哪个 Node ls package.json package-lock.json # 把 engines 和 scripts 打印出来engines 里通常写了作者期望的 Node 范围 node -e const prequire(./package.json);console.log(engines:,p.engines);console.log(scripts:,p.scripts) # 看锁文件版本v1 大致对应 npm 6 时代v2/v3 对应 npm 7 及以上 head -n 5 package-lock.json这三条命令的逻辑很直白engines字段是作者声明的运行范围如果写了14 17就老老实实装 16没写就看锁文件版本lockfileVersion: 1一般是 Node 14 或 16 时代留下的2或3一般是 Node 16 往上。scripts里能看到dev、build、build:prod这些脚本名后面打包环节要用到先记下来。提示engines只是声明npm 默认不会因为你版本不对就拒绝安装它会在最后给你一段警告很多人直接忽略过去然后带着一颗隐雷继续往下走。确认版本后建议用版本管理工具切换不要反复卸载重装。Windows 上常见做法是 nvm-windows装一次就能在多个 Node 版本之间来回切。# 查看本机已装版本 nvm list # 装一个 16 系列的版本具体小版本号按工程实际要求填 nvm install 16.20.2 # 切过去并确认 nvm use 16.20.2 node -v npm -vnvm use之后一定要再跑一次node -v确认因为 nvm-windows 是通过改写 PATH 里的软链接目录来切换版本的偶尔会遇到终端缓存了旧路径的情况关掉终端重开一次就正常了。如果nvm use报权限错误通常是因为当初 Node 是直接用官方安装包装在C:\Program Files下的那个目录需要管理员权限这种时候把原来的 Node 卸掉用 nvm 重新装一遍比修权限省事。2.2 安装路径中文、空格、OneDrive 三个雷踩一个就够折腾半天Node 装在哪其实有讲究。默认安装包会装到C:\Program Files\nodejs而 npm 的全局目录默认在用户目录下比如C:\Users\某某\AppData\Roaming\npm。这里有两个隐患一是「Program Files」中间带空格个别老工具在拼接命令行时不会加引号直接断在空格上二是用户名如果是中文全局包路径里就带了中文某些包在读写缓存时会出问题。我一般把 Node 装到D:\dev\nodejs然后手动把 npm 的全局目录和缓存目录也挪到同一片区域。# 确认当前 node、npm 的真实位置和全局/缓存目录 where node where npm npm config get prefix npm config get cachewhere输出的是实际执行文件路径npm config get prefix是全局包npm i -g装的东西的落点get cache是下载缓存的落点。如果这两个都在用户目录下且路径含中文就动手改# 全局包和缓存都挪到纯英文短路径下 npm config set prefix D:\dev\npm-global npm config set cache D:\dev\npm-cache # 验收重新读一遍配置 npm config get prefix npm config get cache改完prefix之后还有关键一步把D:\dev\npm-global加进系统环境变量 PATH否则你npm i -g装的命令行工具在终端里找不到。加完必须新开一个终端窗口才生效在旧窗口里反复echo %PATH%是看不到变化的这一点每年都能骗到一批人。注意如果工程目录本身放在 OneDrive 同步盘或者桌面同步目录下node_modules那几万个文件的同步会把磁盘 IO 打满安装速度慢到怀疑人生还可能出现文件被占用导致删除失败。工程目录建议放在D:\code\这类不参与同步的位置。2.3 依赖安装镜像、缓存与 EPERM 的三板斧路径和版本都定了才轮到npm install。国内网络环境下直连默认源经常跑到一半卡住常见做法是换成国内镜像源。# 先看当前源再换镜像 npm config get registry npm config set registry https://registry.npmmirror.com # 清理并校验本地缓存排除缓存损坏导致的诡异报错 npm cache verify # 正式安装锁文件存在时首选 ci保证和别人装出来的依赖树一致 npm ci关于npm ci和npm install的取舍有package-lock.json且不想改动锁文件时用npm ci它会严格按锁文件安装先删掉node_modules再全量装速度通常更快也更适合多人协作只在自己加依赖、需要更新锁文件时才用npm install 包名。安装过程中最常见的两类失败处理方式完全不同第一类是网络类的报ETIMEDOUT、ECONNRESET、404 Not Found。先确认镜像源生效再确认是不是某个包在内网私有源上这种情况要在工程里配.npmrc把私有包指到私服地址其余走公共源。第二类是文件占用类的报EPERM: operation not permitted或EBUSY。这基本是上一个进程没退干净或者 Windows Defender 正在扫node_modules里的文件。解决顺序是先关掉所有编辑器里打开该工程的窗口和终端再删目录还删不掉就用管理员权限的命令行删反复出现就在杀毒软件里把工程目录加进排除项。# 删依赖目录的正确姿势先确认没有进程占用再删 tasklist | findstr node # 确认没有残留的 node 进程后 rmdir /s /q node_modules npm ci这套流程走完npm run dev能把开发服务器拉起来前端这一半就算立住了。剩下的问题都会出现在「打包之后」这一段路上也就是下一章的 Nginx。3. Nginx 1.20.2 落地解压、temp 补齐、conf 只改三处Nginx 在这个项目里的角色很明确托管打包后的静态文件顺便把/api开头的请求转发给后端。它本身是个绿色软件解压即用但正因为「解压即用」很多人跳过了目录准备这一步于是就有了开头那行CreateDirectory() failed。这一章按目录、配置、命令三块拆开。3.1 目录规划与 temp 目录结构那行报错的根因在这里先说清楚这个报错是怎么回事。Nginx 处理上传请求体和代理响应时需要把超出内存缓冲的部分临时写到磁盘上落点就是temp目录下的几个子目录比如client_body_temp、proxy_temp、fastcgi_temp。Windows 版的压缩包里这些目录有时是空的解压工具遇到空目录可能不创建Nginx 启动时想去建结果因为路径问题建不出来就直接[emerg]退出。这里的「路径问题」通常有两个来源一是整个 Nginx 目录放在含中文的路径下二是父级目录本身不存在。所以第一步是规划一个干净的路径。我一般用这种结构全英文、无空格、层级浅# 目标结构D:\dev\nginx-1.20.2 # 把解压出来的 nginx-1.20.2 整个目录放到 D:\dev 下 cd /d D:\dev\nginx-1.20.2 # 看一眼顶层结构正常应该有 conf、html、logs、temp 四个目录 dir正常解压出来的顶层目录是conf配置、html默认页、logs日志、temp临时文件。如果temp不存在或者存在但里面是空的就手动补齐。补齐不是只建一个client_body_temp就完事另外几个同类目录迟早也会被用到一次建全省得下次再翻日志# 在 Nginx 根目录下补齐 temp 及全部子目录 mkdir temp mkdir temp\client_body_temp mkdir temp\proxy_temp mkdir temp\fastcgi_temp mkdir temp\uwsgi_temp mkdir temp\scgi_temp # 确认目录结构 dir temp每个子目录负责一类临时文件client_body_temp存客户端请求体比如文件上传proxy_temp存反向代理拿回来的响应fastcgi_temp存 FastCGI 响应uwsgi_temp和scgi_temp对应另外两种协议。这个项目里只用到静态托管和反向代理理论上只有前两个会被真正写入但一次建全的代价几乎为零缺一个就是一个[emerg]。提示如果确认目录都建好了、路径也是纯英文还是报同样的错去logs\error.log里看完整路径。日志里的路径就是你实际生效的路径有时候是配置里prefix或者别的指向了另一个位置而不是你现在这个目录。3.2 nginx.conf 改哪几行静态托管、接口转发、单页兜底conf\nginx.conf是唯一需要动的文件。这份配置的整体结构是worker_processes加events加http我们只关心http里的server块。下面这份是能直接抄作业的最小可用版本改的时候把路径换成你自己的。worker_processes 1; events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; server { listen 80; server_name localhost; # 前端打包产物目录注意用正斜杠 location / { root D:/dev/cangqiong-waimai/dist; index index.html; # 单页应用刷新兜底找不到文件就回 index.html try_files $uri $uri/ /index.html; } # 接口转发/api/ 开头的请求交给后端 location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_connect_timeout 10s; proxy_read_timeout 30s; } } }逐项说明一下关键点这些地方改错一个就白折腾指令作用常见写错法listen 80监听端口浏览器默认访问 80 可省略端口被系统服务占用启动不报错但访问到别的页面root静态文件根目录指向 dist 的绝对路径用反斜杠D:\dev\...部分场景下解析异常try_files找不到文件时回退到index.html只写$uri刷新子路由必 404proxy_pass末尾斜杠决定是否剥掉/api前缀和后端实际接口前缀对不上全部 404proxy_set_header Host传给后端的 Host 头漏写导致后端生成回调地址错误proxy_pass那一行最容易出错重点看末尾有没有斜杠。写成proxy_pass http://127.0.0.1:8080/;时/api/user/list转发到后端会变成/user/list/api被剥掉了写成proxy_pass http://127.0.0.1:8080;不带斜杠则原样转发/api/user/list。后端接口如果本身不带/api前缀就要带末尾斜杠如果后端自己也挂了/api上下文就不要带。这一条对不上浏览器里看到的是一排 404很容易误判成前端打包有问题。改完配置先别急着启动用nginx -t校验语法。这一步能把括号不配对、指令拼错、路径写错这些问题在启动前拦下来比启动失败再回头翻日志省时间。cd /d D:\dev\nginx-1.20.2 # 校验配置语法成功会输出 syntax is ok 和 test is successful nginx -t3.3 启动、重载、停止命令行比双击靠谱很多人习惯双击nginx.exe这个动作在 Windows 上的实际效果是弹出一个黑色窗口然后瞬间消失进程留在后台。问题在于你看不到任何输出配置错了也不知道错在哪而且双击启动的进程当前工作目录是资源管理器给的某些相对路径会解析成别的地方。我更推荐在 Nginx 根目录下用命令行启动好处是能配合-t先校验、能配合tasklist看进程、能配合日志定位。cd /d D:\dev\nginx-1.20.2 # 启动start 会新开一个窗口跑不占当前终端 start nginx # 看进程正常会有 master 和 worker 两个 nginx.exe tasklist | findstr nginx # 改完配置后热重载不中断现有连接 nginx -s reload # 优雅停止等现有请求处理完再退 nginx -s quit几个命令的差别值得记一下start nginx是启动nginx -s reload是重新读配置并平滑重启 worker改nginx.conf之后用它不用停服务nginx -s quit是优雅停止nginx -s stop是快速停止本地开发环境用哪个都行但如果正在传大文件quit更稳。还有一种情况是进程卡死、-s stop没反应那就只能强杀# 强杀所有 nginx 进程用于进程僵死的情况 taskkill /f /im nginx.exe另外提醒一句Windows 下 Nginx 不会注册成系统服务开机不会自动起也没有systemctl可用。本地开发这样挺好随用随起如果要长期挂着就把它写成计划任务或者用第三方服务包装工具别指望它自己常驻。4. 前端产物投放从 npm run build 到 dist 落地前面两章把 Node 和 Nginx 都立起来了但这两者之间还差一段打包。开发模式跑通不代表打包产物能用接口地址、静态资源路径、路由模式这三处都是打包之后才会暴露的问题。4.1 打包前必须改的接口地址别把 localhost 带进产物开发模式下前端工程一般通过开发服务器的代理把/api转到后端配置写在脚手架自己的代理文件里。打包之后这层代理没了请求会直接打到当前页面所在的域名加端口也就是 Nginx 的 80 端口上正好由location /api/接住再转给后端。这个链路要成立前提是打包产物里的接口基地址得是相对路径。常见做法是在工程根目录放一份生产环境变量文件把基地址写成/api# .env.production变量名按工程实际的脚手架约定来 # 值写相对路径交给 Nginx 转发不要写 http://localhost:8080 VUE_APP_BASE_URL/api如果写成了http://localhost:8080那么别人打开页面时浏览器会去访问他自己电脑上的 8080 端口接口全部失败控制台一排ERR_CONNECTION_REFUSED。这个坑在本地自测时完全看不出来因为你自己电脑上后端确实开着——典型的「在我这儿是好的」。改完环境变量就可以打包了。脚本名以package.json里的scripts为准# 按工程实际脚本执行常见是 build 或 build:prod npm run build # 打包完成后确认产物目录 dir dist产物目录里一般是index.html加一个static目录里面按 js、css、img、fonts 分类。static目录里带哈希后缀的文件名不用管那是缓存策略的一部分改了内容哈希会变浏览器自然不会用到旧缓存。4.2 dist 放哪root 和 alias 的区别决定你少不少走弯路打包产物放哪都行只要nginx.conf里的root指对。但有两点得说清楚。第一root和alias不是一回事。root会把location的路径拼接到后面alias是直接替换。在location /下这两者效果一样因为location是根路径但如果写成location /web/ { root D:/dev/dist; }实际找的是D:/dev/dist/web/跟你想的D:/dev/dist/差一层页面必然 404。用location /配root是最不容易出错的组合。第二路径分隔符。Windows 下习惯写反斜杠但 Nginx 配置里最好统一用正斜杠D:/dev/cangqiong-waimai/dist反斜杠在配置解析里是转义字符某些位置会吃掉后面的字符表现出来就是路径不存在。改完路径最稳的验证方式不是打开浏览器而是先在命令行里确认文件真的在那里# 确认 nginx.conf 里写的 root 目录下确实有 index.html dir D:\dev\cangqiong-waimai\dist\index.html4.3 刷新就 404try_files 兜底把子路由接住这是打包部署最高频的问题没有之一。表现是首页能打开点进任意二级页面正常但只要在那个页面按一下 F5立刻变成 Nginx 的 404 页面。原因跟前端路由实现方式有关。单页应用的 URL 由前端脚本接管/order/list这个路径在服务器上根本没有对应的文件或目录。从首页点进去时是前端脚本在做无刷新跳转浏览器没向服务器发请求所以看着正常一刷新浏览器老老实实向服务器请求/order/listNginx 在 dist 目录里找不到这个文件直接返回 404。try_files就是解决这个问题的location / { root D:/dev/cangqiong-waimai/dist; index index.html; # 依次尝试原文件、目录、最后回退到 index.html try_files $uri $uri/ /index.html; }$uri是请求路径本身$uri/是把它当目录再试一次最后的/index.html是兜底——前两个都没命中就把首页内容返回给浏览器前端脚本拿到页面后再根据当前 URL 渲染对应路由。这一行加上刷新 404 就没了。注意try_files只是把页面接住它拦不住/api的请求。如果接口也返回 404问题在proxy_pass那一段别在try_files上反复改。5. 常见问题排查Nginx 起不来、页面白屏、接口不通这一章按「启动阶段」和「访问阶段」分开记录。启动阶段的问题特征是浏览器压根连不上访问阶段是页面能开但内容不对两者的排查入口完全不同前者看logs\error.log后者看浏览器开发者工具的网络面板。5.1 启动阶段三个现象三种根因现象一双击nginx.exe后黑窗一闪而过浏览器访问不了error.log里是CreateDirectory() …\temp\client_body_temp failed (3: The system cannot find the path specified)。原因是 Nginx 启动时找不到它要用的临时目录或者那层父目录压根不存在错误码 3 在 Windows 上就是「系统找不到指定的路径」。常见诱因有两个整个 Nginx 目录放在含中文或空格的路径下以及压缩包解压后没有把空目录带出来。解决方法是把整个目录挪到纯英文短路径然后按 3.1 的清单把temp和全部子目录手工建一遍再nginx -t校验、start nginx启动。这个坑我踩过一次之后现在解压完第一件事就是看temp目录在不在。现象二nginx -t报unexpected }或unknown directive xxx但配置看起来完全正常。原因是配置文件编码。用记事本或者某些编辑器保存nginx.conf时会带上 UTF-8 BOM 头Nginx 解析第一行时会把 BOM 当成指令的一部分于是报出莫名其妙的未知指令。另一种情况是括号真的不配对多删了一行结尾。解决方法是把文件另存为无 BOM 的 UTF-8然后从http {开始逐层数括号用支持显示括号匹配的编辑器打开能一眼看出来。现象三启动不报错tasklist里也有 nginx 进程但浏览器打开 80 端口看到的是一个陌生页面或者提示拒绝连接。原因是 80 端口被别的程序占了最常见的是系统自带的 Web 服务或者其他开发工具。Nginx 在这种情况下有时不会明显报错因为它以为启动成功了实际监听失败。排查命令很直接# 找出占用 80 端口的进程 PID netstat -ano | findstr :80 # 拿 PID 反查是哪个程序注意把 1234 换成上一条查到的 PID tasklist | findstr 1234确认是无关程序占着就taskkill /f /pid 1234干掉或者把listen 80改成 8081 之类不冲突的端口访问时带上端口号。5.2 访问阶段页面能开但数据不对现象四首页打开是白屏控制台报Failed to load resource: 404路径指向/static/js/xxx.js。原因是root指错了层级。比如实际产物在D:/dev/cangqiong-waimai/dist配置里写成了D:/dev/cangqiong-waimaiNginx 就会去D:/dev/cangqiong-waimai/static/js/xxx.js找文件当然找不到。另一种可能是打包时配了非根路径的publicPath产物里的资源引用带了前缀而 Nginx 的location没对应上。解决方法是先用dir命令确认root目录下确实有index.html和static再打开浏览器看请求的具体路径两边对一遍就能定位。现象五页面正常但所有接口报 502 或者 404控制台里请求地址是对的。502 说明 Nginx 转发不出去最常见是后端没起或者端口写错。先确认后端确实在127.0.0.1:8080上监听着netstat -ano | findstr :8080。有监听还 502就看logs\error.log里的connect() failed那一行它会明确写出连不上的目标地址。404 则是proxy_pass的斜杠问题按 3.2 里那张表对一遍前缀。# 绕过浏览器直接测接口转发是否通-i 带上响应头方便看状态码 curl -i http://127.0.0.1/api/user/list这条命令能在不打开浏览器的情况下区分是「转发链路不通」还是「前端调用方式不对」。如果curl通了而页面还是报错问题基本就落在前端的环境变量上了。6. 装完怎么验证五步跑通再交给别人环境这种东西自己电脑上跑通不算数得有一套能重复执行的验证动作。我现在的习惯是交付前不打开浏览器先按顺序跑完下面五步全过了再去点页面。这套顺序是从底层往上层走的任何一步失败都能立刻锁定范围不用在浏览器里瞎猜。第一步确认 Node 和 npm 的位置与版本。node -v npm -v where node npm config get prefix版本要对得上 2.1 里确定的那个where node的输出路径要和npm config get prefix在同一片区域避免出现「装了两个 Node、终端用的是旧的那个」这种玄学问题。第二步确认依赖安装干净。# 依赖装完后跑一次审计重点不是漏洞数量是看有没有装失败的残留 npm ls --depth0npm ls如果报missing或invalid说明依赖树不完整直接rmdir /s /q node_modules加npm ci重来一次别硬撑。第三步确认 Nginx 配置语法和目录就位。cd /d D:\dev\nginx-1.20.2 nginx -t dir temp dir D:\dev\cangqiong-waimai\dist\index.htmlnginx -t输出test is successfultemp下五个子目录都在dist下有index.html这三条同时满足才继续。第四步分层验证访问链路。# 首页是否能拿到 200 curl -I http://127.0.0.1/ # 静态资源是否能拿到 200文件名换成 dist 里实际存在的 curl -I http://127.0.0.1/static/js/app.js # 接口转发是否通 curl -i http://127.0.0.1/api/user/list # 模拟刷新子路由验证 try_files 兜底是否生效 curl -I http://127.0.0.1/order/list这四条分别对应静态托管、资源路径、反向代理、单页兜底。哪条返回 404 或 502就回到对应章节查对应配置比在浏览器里翻网络面板快得多。第五步浏览器实测这三个动作。验证动作期望结果对应问题打开首页页面完整渲染无白屏root层级、资源路径进入二级页面后按 F5页面正常不出现 404try_files兜底触发一次列表查询数据正常返回控制台无红字proxy_pass前缀、后端端口三个动作全过这套前端环境才算真正交付出去。血泪经验是我最早做这套环境的时候是先开浏览器出问题再回头翻日志结果每次都在「到底是前端没打包好还是 Nginx 没配好」之间来回怀疑一个下午能搭进去。从那以后我每次搭完这套环境都强制先走一遍nginx -t加四条curl确认链路从文件到代理都是通的再去点浏览器。顺序对了问题基本一次就能定位。希望帮到你。本文还有配套的精品资源点击获取