企业官网建设流程全解析

做前端的，几乎没人能绕开脚手架上手这道坎。最近带了个新人，第一天问他环境起来没有，他说“起好了，但不知道起好了啥”。这个回答其实特别真实，因为现在跑一条npx create-react-app my-app，几十秒后一个能跑的项目就诞生了，但脚手架到底替你干了多少活、它背后为什么长这样、哪一步出了问题该去哪儿排查，很多人是模糊的。

这篇文章我想认真把React脚手架这件事讲透。不只是告诉你“用哪个命令创建项目”，而是从脚手架的设计思路、选型对比，到配置文件改造、常见坑位排查，把我这几年实际踩过的、调过的经验一次性整理出来。内容适合两类人看：刚学会React基础语法、想弄明白“工程化”是怎么回事的新人；以及已经用脚手架写了一阵业务、但想系统理解内部机制、想按自己团队需求改造模板的进阶开发者。

1. 脚手架的本质是什么：它到底替你做了什么

很多人把脚手架理解成“自动生成代码的工具”，这个说法太片面了。脚手架的真正价值，是把你从环境配置里解放出来，让你直接进入“写业务代码”的状态。你可以把它想象成一家精装修交付的楼盘：开发商已经把水电管线、墙面地面、门窗厨卫全装好了，你拎包入住就行。自己从毛坯开始搭，不是不行，但水电验收、防水测试、布线规划这些活，每样都能耗掉你大量时间和精力。

具体到React脚手架，它默认帮你解决了几件非常关键的事。

1.1 项目结构：约定优于配置

脚手架会生成一套标准化的目录骨架。拿经典的CRA（Create React App）来说，生成出来的基础结构长这样：

my-app/ ├── public/ │ ├── index.html │ └── favicon.ico ├── src/ │ ├── App.js │ ├── App.css │ ├── index.js │ └── index.css ├── package.json └── README.md

public/index.html是应用的HTML入口，src/index.js是JavaScript入口，src/App.js是根组件。这套结构被几百万开发者用了很多年，几乎成了一个事实标准。好处就是团队协作时零沟通成本，任何人接手项目，都不用花时间解读目录意图。

但我要多说一句：标准结构只是起点，不是终点。实际商业项目里，你基本不会只用这几层目录，通常需要扩展出components（通用组件）、services（接口请求）、store（状态管理）、utils（工具函数）、hooks（自定义钩子）等目录。这个扩展动作，脚手架不会替你完成，但理解了它的默认结构以后，你就知道从哪个基准点开始长出你自己的规范。

1.2 构建工具链：一层比一层复杂的翻译工作

浏览器无法直接运行JSX语法和ES6+模块，需要把源代码翻译成浏览器能理解的原生JavaScript，这是构建工具的核心职责。CRA默认集成的是webpack，它做的事情包括：

• JSX语法转换：把<div className="box">这类代码转成React.createElement('div', { className: 'box' })调用。
• ES6+降级：把const、箭头函数、async/await转成更老浏览器能跑的ES5语法。
• CSS处理：支持@import和模块化样式，自动注入到页面中。
• 静态资源处理：图片、字体、SVG等文件，超过一定体积的转成独立文件，小于阈值的内联成Base64，减少请求次数。

这个过程里最核心的工具是Babel。它像一名翻译官，把“新世界”的语法翻译给“旧世界”听。每条规则对应一个转换插件，比如@babel/preset-react负责JSX，@babel/preset-env负责ES6降级。脚手架里这些配置都替你配好了，你写代码时完全感知不到它们在后台拼命干活，只有等哪天构建报错了，你才突然意识到这层翻译机制的存在。

1.3 开发服务器：热更新和代理解决的前后端联调痛点

开发模式下，脚手架会启动一个本地开发服务器。它有两个杀手级功能。第一个是热模块替换（HMR），你保存代码后，页面不会整页刷新，而是只更新被修改的那个组件，React组件的本地状态还能保留。这在调试一个多层嵌套表单的时候特别香，以前改一个字段就要重新填一遍整个表单的日子，就是靠它终结的。

第二个是开发代理。你本地调接口，如果前端跑在localhost:3000，后端跑在localhost:8080，跨域问题就来了。脚手架允许你来一句简单的配置：

// package.json 中的配置 "proxy": "http://localhost:8080"

这样你前端请求/api/user时，开发服务器会自动帮你把请求转发到8080端口，浏览器侧完全感知不到跨域这回事。生产环境一般由网关或Nginx做反向代理，开发阶段用脚手架自带的代理能力就够用了。

1.4 代码质量规则：从第一天就拦住低级错误

脚手架项目里有ESLint和一系列规范插件。ESLint像一名文本审查员，在你敲代码时实时给出提醒。比如你定义了变量但没用，它会划黄线；你用了console.log且团队禁止保留，它会划红线。CRA的默认规则集里还包括了React专属的检查项，比如react-hooks/rules-of-hooks，这条规则专门拦“在条件语句里调用Hook”的写法，因为这会破坏Hook的调用顺序，直接导致组件状态错乱。

很多新手觉得ESLint烦人，动不动报错。但我的看法相反：ESLint是脚手架送你的第一个免费Code Review老师。它把那些能机器判断的错误全替你标出来了，你只需要花点时间改掉，代码质量下限就被兜住了。

2. React脚手架的主流选型：不同场景下的合理决策

“React脚手架”并不是只有一种，市面上主流方案有CRA、Vite、Umi、Next.js等。选哪个，取决于你的项目场景和团队情况。我用一个比较实在的对比表来呈现各自定位。

2.1 四大脚手架横向对比

2.2 怎么选：不是越新越好，适合才重要

如果你是个初学者，我建议直接用CRA打底。为什么？因为CRA的文档量、社区问答量、踩坑记录量是最大最全的。你遇到任何错误信息，基本都能搜到现成解决方案。这对新手期的“自救能力”是很大的保障。

如果你在开一个全新的纯前端项目，团队基础也比较好，Vite是当前最好的体验选择。它冷启动快得离谱，而且原生支持JSX和TypeScript，无需额外配置。我做过一个项目，从CRA迁到Vite之后，开发服务器的启动时间从8秒降到了不到1秒，改动文件后的热更新也是毫秒级响应，体验差距非常大。

如果你做的是中后台系统——就是那种左边菜单、右边表格、顶部导航的管理界面——Umi的约定式路由、权限方案、数据流方案都是现成的。团队不用从零去规划路由和状态管理怎么组织，直接按Umi的套路写就行，开发节奏会快很多。

如果你做的是需要SEO的站点，或者项目里想顺手写点服务端逻辑，Next.js是标配。它支持页面级预渲染，搜索引擎能直接抓到页面内容，对流量获取至关重要。

我的建议是：不要为了追新而换脚手架。脚手架迁移的成本比大多数人想象的高，除了项目文件结构调整，还有依赖升级、构建逻辑差异、潜在运行行为变化。如果没有强烈的痛点和收益，老项目继续用原方案往往更稳。

3. 基于CRA的工程化进阶：从默认模板到团队规范的改造实录

这一章是全文的干货核心。我会围绕CRA的默认项目，讲讲如何把它改造成一套符合团队规范的工程模板。整个过程涉及自定义模板结构、修改构建配置、接入代码规范工具链、实现按需加载和构建优化。

3.1 扩展目录结构的标准姿势

默认的src目录只有几个文件，根本撑不住真实业务。我通常会在src下规划出这些目录：

src/ ├── api/ // 接口请求封装 ├── assets/ // 静态资源（图片、字体等） ├── components/ // 通用业务组件 ├── hooks/ // 自定义Hooks ├── layouts/ // 页面布局组件 ├── pages/ // 路由页面 ├── routes/ // 路由配置 ├── store/ // 全局状态管理 ├── styles/ // 全局样式 ├── utils/ // 工具函数 └── index.js // 入口

划分依据是“功能归属”，而不是“文件类型”。比如components放的是可复用的通用组件，pages放的是跟路由一一对应的页面级组件。这样划分后，新人进项目，靠目录名就能猜到代码应该放在哪里，不需要翻文档。

有个细节值得注意：跨目录的引用，尽量采用绝对路径或别名，避免一长串../../../。一条路径里出现三个或以上的../，基本说明目录设计出了问题，或者该用别名机制了。

3.2 用craco改造webpack配置而不eject

CRA有一个让人又爱又恨的设计：所有构建配置都被黑盒封装在react-scripts内部。如果直接跑npm run eject，会把几百行配置文件全部弹射出来，之后你就得自己维护它们，以后升级CRA还会遇到冲突。这时候就该craco（Create React App Configuration Override）出场了，它允许你在不eject的情况下覆盖webpack、Babel、ESLint等配置。

安装craco后，项目根目录新建craco.config.js：

const path = require('path'); module.exports = { webpack: { alias: { '@': path.resolve(__dirname, 'src') } } };

然后修改package.json里的启动命令：

{ "scripts": { "start": "craco start", "build": "craco build", "test": "craco test" } }

这样一来，你在组件里就能写import Button from '@/components/Button'，不用再受../连击的折磨。craco的定位是“最后一公里”的配置补充方案，它不接管全部配置，只给你需要的覆盖入口。本质上，它拦截了CRA内部的webpack配置对象，在它生成最终配置之前插入你的修改逻辑，所以你改到的每一个字段，都是真正生效的。

3.3 多环境变量管理的正确姿势

CRA默认支持环境变量，但有个限制：只有以REACT_APP_开头的变量才会被注入到process.env中。这个设计是为了防止意外把服务器密钥等敏感信息暴露到前端代码里。

我一般会在项目根目录建三个文件：

• .env（所有环境共用）
• .env.development（仅开发环境加载）
• .env.production（仅生产环境加载）

内容示例：

REACT_APP_API_BASE_URL=https://api.example.com REACT_APP_ENV=production

读取方式是在代码里直接访问：

const apiBaseUrl = process.env.REACT_APP_API_BASE_URL;

这里有个关键坑：修改.env文件后，必须重启开发服务器才能生效。因为环境变量是在构建启动时被读取并注入到代码里的，热更新不会重新执行这个注入动作。我见过好几个同事改了环境变量，刷新半天页面没变化，最后才发现是没重启。

3.4 接入ESLint + Prettier + Husky的完整代码检查链

单靠CRA内置的ESLint规则，只能拦住语法级问题。想统一团队代码风格，还需要接上Prettier做格式化，用Husky做Git提交前的自动检查。

Prettier的定位是“代码格式化器”，它不管代码逻辑对不对，只管格式统不统一。比如字符串用单引号还是双引号、行尾要不要分号、缩进多少空格，这些交给它统一处理。我推荐的安装方式是作为开发依赖：

npm install --save-dev prettier

项目根目录创建.prettierrc配置文件：

{ "singleQuote": true, "semi": false, "trailingComma": "none" }

接着是Husky。它能在git commit之前触发钩子函数。配合lint-staged，实现“只检查暂存区里的文件”，避免全量检查耗时过长。安装配置命令：

npm install --save-dev husky lint-staged npx husky install npx husky add .husky/pre-commit "npx lint-staged"

然后package.json里加入：

{ "lint-staged": { "src/**/*.{js,jsx,ts,tsx}": ["prettier --write", "eslint --fix"] } }

这套链路走通之后，每次提交代码之前，改了哪些文件就会自动格式化、自动做ESLint修复。如果有错误，提交会被拦下，直到你处理完。一开始团队可能觉得“提交好烦”，但一段时间后，代码库的整体可读性会有明显提升。

3.5 路由懒加载和代码分割的实战配置

单页应用有个通病：打包产物把所有页面组件都打到一个main.js里，首屏下载时间会越来越长。解决思路是“让哪个页面被访问到了，才去加载哪个页面的代码”，这就是路由懒加载。

React官方方案是React.lazy配合Suspense。改造前你的路由可能是这种写法：

import Home from './pages/Home' import About from './pages/About'

这种静态导入，webpack会把所有页面全部打包进同一个文件。改成懒加载后：

import { lazy, Suspense } from 'react' const Home = lazy(() => import('./pages/Home')) const About = lazy(() => import('./pages/About')) function App() { return ( <Suspense fallback={<div>页面加载中...</div>}> <Switch> <Route path="/" component={Home} /> <Route path="/about" component={About} /> </Switch> </Suspense> ) }

其中lazy(() => import('./pages/Home'))这个写法告诉webpack：“这个组件单独切成一个chunk文件，只在需要渲染它的时候才去下载。”Suspense则负责等待加载过程的占位UI。

构建之后，你会在产物目录里看到多个[name].[hash].js文件，而不是只有一个巨大的入口文件。首屏只要加载跟当前页面相关的那个chunk以及公共chunk，体验上的提升非常直接。

3.6 构建产物的体积分析和优化思路

用npm run build完成构建后，CRA会在控制台打印每个chunk的体积。这时候如果你想深入查看哪些模块占了空间，可以加一个分析插件。craco配置示例：

const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer') module.exports = { webpack: { plugins: { add: [ new BundleAnalyzerPlugin({ analyzerMode: 'static', reportFilename: 'bundle-report.html' }) ] } } };

执行构建后，会生成一个可视化报告页面，清晰展示出每个依赖包占的体积比例。我优化过的一个实际项目，用这个工具发现一个图表库竟然占了打包体积的1/4以上，之后改用按需引入的方式，产物总大小直接降了30%。

优化思路有几个方向：一是代码分割，把第三方依赖跟业务代码分开打chunk，利用浏览器缓存减少重复下载；二是按需引入，比如lodash别一次import _ from 'lodash'，改用import { debounce } from 'lodash'，很多组件库也支持按需加载；三是去除生产环境的sourcemap，它只是调试用的，非常大，生产环境一般不需要留。

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

脚手架用久了，会遇到一些典型问题。我整理了一份速查表，再挑几个高频问题展开讲讲排查思路。

4.1 脚手架日常问题速查表

4.2 全局CSS污染问题：为什么我只改了按钮样式，整个页面都变了

这是React项目里最经典的样式冲突案例。你在一个组件里写了：

button { background: red; }

因为非模块化CSS默认是全局的，这个样式会被应用到页面里所有button元素，其他组件里的按钮全变红了。

排查思路：看className有没有带上文件名的哈希后缀。如果类名是Button_button__2k3h1这种带后缀的形式，说明使用了CSS Modules；如果就是单纯的button，那就是普通全局样式。

解决方案有两个方向。一是用CSS Modules，样式文件名改成Button.module.css，然后组件里这样引入：

import styles from './Button.module.css' function Button() { return <button className={styles.button}>点击</button> }

这样每个类名都会被构造成唯一值，从源头避免冲突。二是约定命名规范，所有样式类名前加组件名前缀，比如btn-primary、btn-danger，用BEM方法论来约束。我个人的建议是：新项目直接用CSS Modules或Tailwind之类的原子化方案，旧项目至少统一命名规范。

4.3 “Port 3000 is already in use”的完整处理流程

这个报错信息让人一看就烦。出现原因很简单：CRA默认用3000端口，但这个端口已经被别的进程占了。

我的排查流程是：

1. 查看占用进程：lsof -i :3000（macOS/Linux）或netstat -ano | findstr :3000（Windows）。
2. 判断那个进程是否可关。如果是你自己跑的其他项目，启动新项目时换个端口就行：PORT=3001 npm start。
3. 如果占用的进程是僵尸进程或不认识的，用kill -9 进程ID强制结束。
4. 如果不想每次启动都手动改端口，可以在项目根目录创建.env.development文件，写入PORT=3001，这样每次启动自动用这个端口。

我发现一个习惯值得养成：启动新项目前，先看一眼要用的端口是否空闲。这个习惯能省下很多无谓的排查时间。

4.4 代理配置失效的排查思路

开发模式下配置了"proxy": "http://localhost:8080"，但请求/api/user时还是404。可能的原因有几个。

第一种是代理目标地址错了。先把目标地址在浏览器里直接访问一下，确认后端服务真的能通。很多次排查到最后，发现是后端服务忘了启动。

第二种是代理配置只支持http-proxy-middleware的默认行为，不支持正则匹配或复杂路径重写。如果需要把/api/user转发到/v2/user这种路径重写，就得换用http-proxy-middleware来显式配置。

const { createProxyMiddleware } = require('http-proxy-middleware') module.exports = function (app) { app.use( '/api', createProxyMiddleware({ target: 'http://localhost:8080', changeOrigin: true, pathRewrite: { '^/api': '' } }) ) }

把这段代码放在src/setupProxy.js里，CRA会在开发服务器启动时自动加载。

第三种情况是请求没经过代理。如果你用axios请求时写的是完整域名http://localhost:3000/api/user，方向没问题；但如果写的是http://localhost:8080/api/user，就绕过了开发服务器，代理自然不生效。正确做法是请求路径写成相对路径/api/user，让浏览器把请求打到开发服务器上，再由它转发。

4.5 React版本与脚手架版本的兼容性问题

React 18以后，同时存在18和19两条版本线，很多团队还在用React 17甚至16的老项目。脚手架生成的模板默认绑定的是创建时的最新React版本。如果你接手的是旧项目，跑新版本脚手架然后手动改React版本，很容易遇到依赖不兼容的问题。

一个很常见的场景：项目里用的是React 17，但脚手架模板生成的是React 19的启动代码，比如ReactDOM的挂载方式变了、某些生命周期钩子被废弃了，直接跑起来就是一堆警告甚至报错。

我的建议是：别把脚手架当成一次性初始化工具，要把它当成项目的一部分长期维护。创建项目时锁定依赖版本，升级版本时看一下官方迁移指南，别贸然跳大版本。团队里如果有多个项目，最好统一React和脚手架的基础版本，避免每个项目的依赖天差地别，维护成本会成倍增加。

5. 最后再聊几句实在的经验

做了这些年前端，脚手架这个工具我换来换去，但有些体会是共通的。

第一个体会，脚手架只是起点，不是终点。它给你一套默认约定，但真正决定开发效率的，是你在默认约定之上长出来的工程规范——目录结构怎么划分、状态管理怎么组织、接口层怎么封装、样式方案怎么统一。这些不靠脚手架自动生成，需要你结合团队情况去设计。

第二个体会，遇到问题先看构建输出，再看文档，最后才搜答案。脚手架相关的报错信息，大部分在控制台里已经给出了明确的线索。比如Module not found会直接告诉你是哪个文件找不到，SyntaxError会指出你在哪一行写错了语法。学会读错误信息，比会复制粘贴别人的解决方案更重要。

第三个体会，理解脚手架，是理解现代前端工程化的入口。如果你能把webpack、Babel、ESLint、环境变量、代理这些概念都搞清楚，再看别的框架的工程化方案，会发现它们底层思路大同小异。脚手架只是把复杂的东西包了一层壳，壳里面的原理，值得花时间弄明白。

最后一个实用建议：定期更新脚手架本体和依赖。版本更新通常包含性能优化、安全修复和新特性支持。长时间不更新的项目，积攒的版本债会让人非常难受。我见过一个项目停在CRA 3时代，想升到5，结果一路报错，前后折腾了两周才完全跑通。定期小步更新，远好过憋个大招一次性升级。