企业官网建设流程全解析

"前端工程师做Demo谁不会？好看、丝滑、交互惊艳，本地一跑，效果图直接发群里，大家都说牛。但往往最打脸的一刻就在上线那两天——白屏、404、接口报错、字体图片全裂，用户在浏览器里看到的东西和你在自己电脑上看到的完全不是同一个东西。"

这是我在FDE落地实战系列里的第三篇。前两篇我们聊了FDE岗位的工作边界和需求拆解，今天这篇专门聊聊那个让很多前端工程师半夜心梗的经典问题：为什么Demo很好看，一上线就出问题？FDE的日常不只是还原UI、写交互，更关键的一段路是从“能跑”到“能上线”。这篇文章就把这条路上的坑一个个踩给你看，顺便给出一套可以直接照抄的落地流程。

1. Demo和线上，本质上是两个世界

1.1 你以为在跑同一个项目，其实不是

很多前端新人会有一个错觉：代码是我写的，本地能跑，打包上传服务器，顶多就是路径问题。但实际走下去会发现，本地环境和线上环境之间的差异，比你想象中大得多。

我通常会把这种差异拆成三个维度：

**运行环境差异。**本地开发用的是开发服务器，比如vite的devServer、webpack的devServer或react的npm start，它们默认做了热更新、路径重写、跨域代理。你访问的地址是http://localhost:5173，所有资源都是动态编译的。但线上环境是一个静态文件服务器，通常是Nginx，它不会帮你做任何编译，只负责把文件吐出去，路径匹配、MIME类型、缓存策略全得你自己配好。

**数据环境差异。**Demo阶段大概率是写死数据，或者用Mock来模拟接口。而线上要接真实后端服务，跨域限制、接口鉴权、网络波动、数据格式变化，每一个都是新的变量。

**用户环境差异。**你自己用的是公司配的Mac，Chrome最新版，网络带宽充足。真实用户用的是五花八门的手机、各种版本的浏览器、时快时慢的4G/5G。你在本地没见过的兼容性问题，用户能变着花样帮你复现。

这三个维度放到一起，你就会明白：单独把“本地能跑”当作上线标准，本身就是一件很危险的事。

1.2 Demo模式下，哪些东西被“偷偷惯坏了”

我得说句实话：Demo本身没有错，它在前期的需求对齐和设计验证阶段非常重要。问题在于Demo模式下有些东西被简化了，而简化掉的部分恰好是线上最容易出问题的部分。

第一是跨域。本地开发时，前端框架的脚手架都会配置一个proxy代理，把/api这种请求转发到后端服务器，浏览器根本感知不到跨域问题。但打包成静态文件部署之后，就不再走这个代理了。如果线上没有用Nginx做反向代理，而是让前端直接去请求http://api.xxxx.com这种地址，那么浏览器会在CORS策略上给你上一课。

第二是路由。很多Demo用的是BrowserRouter之类的前端路由，本地开发怎么刷新都没事。但线上部署时，如果Nginx没有配置try_files，用户刷新某个子页面比如/product/123，服务器去找这个路径下的文件找不到，直接就报404。

第三是环境变量。Demo里大家习惯把接口地址写死，或者用本地环境变量顶一下。打包时如果没有区分development和production，很可能会出现“本地跑得好好的，生产环境也在请求localhost”的尴尬情况。

第四是依赖包版本。不少朋友在Demo阶段喜欢用“最新版本”的依赖，今天装一个beta版的UI库，明天更新一个组件版本。本地跑没问题，但打包到线上时因为依赖版本兼容性问题，编译失败或运行时出错，排查起来特别费劲。

所以，与其责怪“Demo欺骗了我”，不如承认一个现实：Demo的目标是证明方案可行，上线的目标是保证交付稳定。这两件事中间，还隔着一整套工程化收尾工作。

2. 上线翻车的高频问题清单

这一节我直接把多年踩坑经验里最典型的几类问题列出来，每类都给了现象、原因和排查方向。不管你是第一次部署个人项目，还是在公司里负责前端交付，都可以对照着看。

2.1 静态资源与路由路径配置错误

这是前端部署翻车的Top 1问题，特征非常明显：打开首页正常，但刷新一个二级页面就404；或者页面能打开，但所有的图片、CSS、JS文件全部加载失败。

原因基本出在打包配置里的base或publicPath上。Vite是base，webpack是publicPath，CRA是homepage。如果你的项目部署在域名根路径，问题不大；但一旦部署在子路径下，比如https://example.com/abc/，而构建配置里仍然默认写成/，那么所有资源都会去请求根目录，自然就全部404了。

这里给一个实战中的建议：部署前先确认部署路径，再写构建配置。比如Vite项目部署在子路径，应该在vite.config.ts中这样设置：

// vite.config.ts export default defineConfig({ base: '/abc/', // 改成实际部署的二级路径 })

刷新404背后的路由配置则要在Nginx层面解决：

location / { try_files $uri $uri/ /index.html; }

try_files的作用是：当URL匹配不到真实文件时，回退到index.html，让前端路由接管接下来的处理。这句话是SPA应用部署的命脉，不知道这一行配置的话，刷新404就是必然的。

2.2 接口Mock和跨域问题

做Demo的时候，Mock很方便，常见方案有msw（Mock Service Worker）、json-server，或者直接在代码里if else一段假数据。问题是很多人在上线前忘了关掉这些Mock逻辑，或者忘了处理跨域。

我见过一个项目，前端页面流转很顺畅，自以为接的是真实接口，实际上代码里有一段被注释掉一半的Mock逻辑，导致线上数据死活不对劲。

另外跨域这块，一旦前端和后端不在同一个域名下，就需要处理CORS或者代理。我的建议是：能用Nginx反向代理就不要让浏览器直接跨域。在Nginx配置里加一段：

location /api/ { proxy_pass http://backend-server:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

这样做的好处是，前端代码里的接口地址统一写成相对路径/api/xxxx，线上和本地的逻辑一致，跨域问题从根本上避免了。本地开发再通过Vite的proxy代理到同一个后端地址，开发体验和线上行为高度趋同。

2.3 构建体积过大导致白屏和卡顿

Demo阶段很少有人关心包体积，反正本地加载快。但到了线上，用户的网络环境千差万别，一个几MB甚至十几MB的JavaScript文件会让首屏加载非常煎熬。

我遇到过一个实际项目：一个管理后台，没做路由懒加载，所有的业务代码打包成一个chunk，压缩后4.8MB，用户访问首页需要先下载这个4.8MB的文件，加上并发限制和弱网，完全渲染出来要好几秒，体感极差。

解决这个问题的手段有很多，优先级从高到低依次是：

• 路由懒加载：按页面拆分代码块，用const UserPage = React.lazy(() => import('./pages/User'))这种模式，访问哪个页面才下载哪个页面的代码。
• 第三方库按需加载：UI库不要整体引入，用ESM按需导入。
• 构建产物分析：用rollup-plugin-visualizer或webpack-bundle-analyzer看一下哪些模块体积占比高，针对性地做拆分或替换。
• 静态资源处理：图片压缩、转WebP、合理设置缓存。

对于Vite项目，最简单的路由懒加载写法如下：

// 路由配置 const routes = [ { path: '/home', component: () => import('@/pages/Home.vue') } ]

这样打包后，每个路由页面会生成独立的chunk文件，首屏只加载首屏需要的代码，其他页面按需下载，首屏性能是肉眼可见的差异。

2.4 兼容性和真机适配

Demo基本都在电脑浏览器里跑，真机适配很容易被忽略。我复盘过几次线上事故，最典型的是这么几类：

window或document对象在服务端渲染（SSR）环境下不存在，导致首屏报错；某些老旧浏览器不支持ES6新语法（比如可选链?.和空值合并??），白屏没商量；移动端键盘弹起遮挡输入框；iOS Safari对100vh的处理有历史遗留问题。

对于兼容性问题，没有一劳永逸的方案，只能靠两条腿走路：一条是构建层面加@vitejs/plugin-legacy或@babel/preset-env进行语法降级；另一条是真机测试列表了，至少要覆盖iOS Safari、Android Chrome、微信内置浏览器这三种常见容器。

2.5 多端打包与容器差异

近期经常有朋友问到鸿蒙Demo打包成hap、hsp、har的问题，还有Android上Kotlin Compose写的Demo在上线时遇到的签名和权限问题。这里多说一句：凡是涉及多端打包的场景，Demo和线上之间的差异会进一步放大。

比如鸿蒙应用里的hap包，本地调试可以直接通过DevEco Studio跑起来，但正式分发时需要签名配置、权限声明、版本号等一堆东西。Android的Compose项目，debug构建和release构建的签名不同、混淆配置不同，如果不提前把本地的debug签名留在代码里，上线后更新就是个坑。

移动端项目和大前端项目的共同思路是一致的：Demo阶段就要把正式/测试的环境区分做进去，不要让debug包的配置和release包耦合在一起。否则等上线前再拆，时间和风险都翻倍。

3. 从Demo到上线的完整落地路径

聊完了问题清单，下面给出一套从Demo到上线可以直接落地的流程。这一节不写空话，从构建配置、Docker部署、Nginx配置到上线验证，按步骤走一遍。

3.1 第一步：整理环境变量，区分不同环境的配置

很多人上线翻车的根源就一句话：“环境变量没分清楚”。本地、测试、生产各需要什么接口地址、是否需要Mock、日志输出级别是多少，这些都应该通过环境变量控制，而不是每次手动改代码。

前端项目通常用.env文件来管理。Vite项目里可以建立以下文件：

.env.development # 本地开发环境 .env.production # 生产环境 .env.staging # 测试/预发环境

文件里的内容类似于：

# .env.production VITE_API_BASE=/api VITE_MOCK_ENABLED=false

然后代码里统一读取：

const apiBase = import.meta.env.VITE_API_BASE const mockEnabled = import.meta.env.VITE_MOCK_ENABLED === 'true'

这样每次打包时，构建工具会自动加载对应环境的变量。不要把接口地址写死在代码里，这是第一条铁律。

3.2 第二步：配置构建优化，控制产物体积

在构建配置里，我一般会固定做三件事：代码分割、压缩、动态polyfill。

以Vite为例，一个基础优化版本是这样的：

// vite.config.ts import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import legacy from '@vitejs/plugin-legacy' export default defineConfig({ plugins: [ vue(), legacy({ targets: ['defaults', 'not IE 11'], }), ], build: { outDir: 'dist', sourcemap: false, rollupOptions: { output: { manualChunks: { vueBasic: ['vue', 'vue-router', 'pinia'], uiLibrary: ['ant-design-vue'], }, }, }, }, })

manualChunks的作用是把公共依赖单独拆包，利用浏览器缓存机制，避免每次业务代码变动导致第三方库也要重新下载。这在长期迭代的项目里收益特别明显。

另外，记得关掉sourcemap。线上环境开启sourcemap不仅增加体积，还等于把源代码暴露给所有人。

3.3 第三步：用Docker镜像固化部署环境

问“前端怎么使用Docker部署项目上线”的朋友非常多，这里统一回答一下：前端用Docker部署的核心目的不是花哨，而是让构建和运行环境保持一致，避免“本机能跑服务器跑不了”的玄学问题。

前端Docker的一般做法是两阶段构建。第一个阶段用Node镜像来安装依赖并打包，第二个阶段用Nginx镜像来承载静态文件。这样做的好处是最终镜像体积很小，只有静态文件和Nginx配置，不包含Node环境和node_modules。

一个可直接使用的Dockerfile如下：

# 第一阶段：构建 FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build # 第二阶段：运行 FROM nginx:1.27-alpine COPY --from=builder /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]

注意一个细节：npm install和npm run build分开写，是为了充分利用Docker的层缓存。如果你的代码没有变化，而node_modules缓存还在，那镜像构建速度会快很多。

3.4 第四步：配置Nginx，解决路由、代理和缓存

Nginx配置是整个前端上线的核心，很多你以为是代码问题的事故，其实都是Nginx配置问题。这里给出一份经过多次实战验证的完整配置模板：

server { listen 80; server_name your-domain.com; gzip on; gzip_min_length 1k; gzip_types text/plain text/css application/javascript application/json image/svg+xml; # 静态资源缓存：文件名带 hash 的文件可以长缓存 location /assets/ { expires 30d; add_header Cache-Control "public, immutable"; } # 前端路由回退 location / { try_files $uri $uri/ /index.html; } # 接口反向代理 location /api/ { proxy_pass http://backend-server: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; } }

这里最值得留意的是缓存策略。带hash的文件（如index.8f2a1c.js）内容变了文件名就变了，可以放心用immutable长缓存；但index.html本身一定不能缓存，否则前端每次发版，用户拿到的都是旧页面。

3.5 第五步：域名、HTTPS与上线后的验证

域名和HTTPS是上线前的最后一公里。现在申请HTTPS证书已经很成熟了，使用certbot之类的工具可以自动申请和续期。HTTPS不是加分项而是必选项：涉及登录鉴权的接口，如果不是HTTPS，token很容易在传输过程中被截获。

上线后的验证不能只看首页能打开，建议按以下清单走一遍：

• 强制刷新页面，确认能拿到最新版本
• 手动刷新一个二级路由，确认不404
• 打开浏览器DevTools的Network面板，看静态资源是否都是200，有没有404请求
• 找一个弱网环境（DevTools里可以模拟），确认首屏加载可接受
• 按真实用户的操作路径走一遍，包括登录、跳转、退出
• 检查控制台有没有报错，特别是跨域和资源加载相关的错误

4. 常见问题与排查技巧实录

这一节整理一份问题排查速查表，方便你在上线出问题时按图索骥。这些都是我当时一个个线上事故试出来的经验，踩过的坑我只说一遍。

为了让你更直观地理解排查思路，我挑两个高频情况展开说。

**白屏排查通用路径。**先打开浏览器DevTools的Console和Network，看有没有红色报错和4xx/5xx请求。如果是资源404，那就是路径问题；如果是语法错误，一般会直接提示哪个js文件哪一行；如果是运行时错误比如Cannot read properties of undefined，就需要用sourcemap定位代码或直接从报错信息反推业务逻辑。白屏的大概率原因，80%是“资源没加载到”或“JavaScript执行出错”，只有极少数是浏览器不兼容。

**构建报错排查通用思路。**例如有朋友遇到过project build error: non-resolvable parent pom for com.example:demo:0.0.1-sn这种Maven构建报错，这种错误本质上是依赖找不到。优先检查本地Maven仓库里有没有对应依赖，再看仓库地址能不能访问，接着检查代理配置是不是拦截了下载。这类问题在CI环境里特别常见，解决方案一般就是确认settings.xml里的镜像源配置是可用且完整的。

5. 从一个好看的Demo到一个能交付的线上项目

上面讲了很多具体操作，这一节我想聊聊比操作更重要的东西：FDE视角下的交付思维。因为工具和配置都是可以学的，但如果在认知层面不转变，就算这次上线成功了，下次换个项目还是会踩类似的坑。

5.1 FDE的职责不是“做页面”，而是“保上线”

FDE岗位的工作内容绝对不只是把UI稿做成页面。你还需要考虑页面在不同环境下是否可用、交互在弱网下是否合理、数据异常时是否有兜底方案、发版后如何快速发现问题、出现问题后能不能快速回滚。

我见过一些前端同学，自己写的页面在开发环境里反复点，觉得没有问题，提测后测试一上手就发现一堆边界情况。其实这不能全怪测试，很多时候是因为开发环境用的数据太“完美”了。真实的接口返回可能是延迟的、可能是500的、可能是字段缺失的，你的页面设计没有考虑到这些情况，那上线后用户看到的就是错误页面。

所以在开发过程中，我习惯性地会问自己几个问题：接口挂了怎么展示？用户弱网时有没有loading反馈？字段为空会不会导致页面崩溃？权限不足时按钮是隐藏还是置灰？这些问题在你设计Demo的时候可能不重要，但在线上体验中就是致命的细节。

5.2 最少必要工程化清单

很多独自开发或小团队协作的朋友担心工程化太重，导致开发效率下降。这里我给一个“最少必要”的清单，不做全量标准化的捆绑，但至少保证上线可维护：

• 版本管理 每次发布使用Git tag，方便出问题时的版本回溯。
• 环境配置 三个基础环境（dev/test/prod）的配置从.env文件中拆分，而不是改代码。
• 构建脚本 把构建命令和输出目录固定下来，本地、CI、Docker统一用同一条命令。
• 日志上报 前端至少做一次错误捕获，把js运行时错误和资源加载错误上报到监控平台，哪怕是简单地把信息发到一个日志接口。这一步主要是为了线上问题不再靠用户截图反馈。
• 发布回滚预案 Docker镜像保留上一版tag，出问题能快速切回旧版本。

5.3 拿Demo做过关评审时，多问一句“上线了怎么办”

最后分享一个我在实际工作中的习惯：每当我们做完一个功能，在给产品或设计做演示的时候，除了展示效果，我都会追问一句“如果这里上线了，我们怎么验证、怎么监控、怎么回退”。这句话在Demo阶段显得有点扫兴，但每次都能把很多潜在的线上事故提前消灭在评审阶段。

这其实也是FDE岗位真正的价值所在：你不仅是把设计稿变成代码的执行者，你是整个前端交付链路的质量负责人。

写到这里，我想起自己第一次独立部署前端项目的样子：本地运行得好好的，自信满满上了服务器，结果白屏了一下午。后来发现只是忘了配置try_files，刷新二级页面就404，用户访问倒是正常，但谁知道哪个用户会手滑刷新一下呢。

那一下午的教训换来的经验是：从此以后，每做一个前端项目，我先把Nginx配置和构建路径想明白，再动手写页面。因为这些底层的部署逻辑，决定了你的页面最终能不能被用户正常访问。

希望这篇FDE落地实战能帮你在上线环节少走几次弯路。下次Demo演示完，别急着庆祝，先想想：如果这个页面现在就要部署到服务器上，你的base、proxy、try_files、缓存策略都准备好了吗？