换成淘宝源试试

React 入门实战：从安装到第一个应用，踩过的坑都帮你绕过

起因：为什么我要写这篇教程？

事情得从去年说起。那时我们团队要启动一个内部的管理后台项目，需要快速迭代、组件化开发，同时保持良好的可维护性。React 在业内已经很成熟了，我们决定尝试使用它作为前端技术栈的核心。

但问题来了：虽然我之前做过 Vue 项目，对现代前端框架并不陌生，但真正上手 React 还是头一回。在搭建环境、写第一个组件时遇到了不少坑，比如 create-react-app 初始化失败、Babel 和 ESLint 配置出错、路由不生效……那段时间真是“一边查文档一边骂人”，不过也收获了很多宝贵经验。

今天我就想以第一人称视角，结合这个真实的项目背景，带你从安装开始，一步步完成 React 的入门之旅，并分享我在过程中遇到的问题和解决方法。这篇文章不是那种“Hello World 灌水教程”，而是来自真实战场的经验总结。

---

项目背景与挑战：一个典型的中台系统雏形

我们要做的系统是一个面向运营人员的内容管理系统（CMS），功能主要包括：

• 文章列表展示与筛选
• 文章详情页面
• 内容编辑
• 用户权限管理（简单版）

虽然看起来不算太复杂，但考虑到后续可能需要扩展模块、支持多人协作开发，我们必须选择一个结构清晰、组件化能力强的框架。React 正好满足这一需求。

初期团队成员包括我本人在内共有三人，其中两个是从 jQuery + 模板引擎转型而来的后端同学，所以整个项目的前端部分更像是从零开始教学+实操的过程。

---

解决方案思路：如何构建我们的第一个 React 应用？

Step 1：选型 & 初始化项目

最初我们考虑手动配置 Webpack，毕竟这样能更灵活控制项目结构，但我很快打消了这个念头——对于刚入门的团队来说，从零配置成本太高。于是果断选择了官方推荐的脚手架工具：

npx create-react-app cms-dashboard

这一步还算顺利，除了公司网络导致 npm 包下载失败了一次，换了个镜像源就搞定了。

Step 2：目录结构调整

默认的 src/ 结构太简单了，不适合中大型项目。我们做了如下调整：

src/
├── assets/              # 图片资源
├── components/          # 可复用组件
├── pages/               # 页面级组件
├── routes.js            # 路由定义
├── App.js
├── index.js

Step 3：引入必要的依赖

为了实现基础的功能和更好的用户体验，我们添加了以下库：

npm install react-router-dom axios antd dayjs normalize.css

• react-router-dom：用于页面跳转
• axios：接口请求
• antd：UI 组件库（提高开发效率）
• dayjs：轻量的时间格式处理
• normalize.css：样式重置，提升浏览器兼容性

---

关键代码实践：从 Hello World 到结构初现

初始化入口文件 index.js（没改什么）

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

修改后的 App.js（加入路由）

import React from 'react';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Home from './pages/Home';
import ArticleDetail from './pages/ArticleDetail';

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/article/:id" element={<ArticleDetail />} />
      </Routes>
    </Router>
  );
}

export default App;

基础组件示例：文章卡片组件（components/ArticleCard.js）

import React from 'react';
import dayjs from 'dayjs';
import './ArticleCard.css';

function ArticleCard({ title, author, publishTime, summary }) {
  return (
    <div className="article-card">
      <h3>{title}</h3>
      <p>作者：{author}</p>
      <p>发布于：{dayjs(publishTime).format('YYYY-MM-DD')}</p>
      <p className="summary">{summary}</p>
    </div>
  );
}

export default ArticleCard;

是不是很简单？但就是这样一个个组件慢慢堆积起来，构成了整个系统的界面基础。

---

踩过的坑 & 实战经验分享

这里我就不罗列一堆错误日志了，直接说几个关键点以及我当时的应对思路：

🧱 1. 创建项目时卡住 or 安装失败

这是很多人新手都会遇到的问题。常见原因有两个：

• 网络问题：国内访问 npm registry 较慢
• Node.js 版本不匹配：建议使用 16.x 或 18.x LTS 版本

解决办法：

npm config set registry https://registry.npmmirror.com

# 清除缓存
npm cache clean --force

# 或者用 yarn
yarn create react-app my-app

🧱 2. 路由不生效，页面空白或报错

当时我们误以为 <BrowserRouter> 是全局唯一根组件，结果多个地方嵌套使用，导致路由失效。

教训：确保整个项目只使用一次 <BrowserRouter>，并在最外层包裹 <App />，再在里面定义 <Routes> 和 <Route>。

🧱 3. ESLint 报红警告太多，根本看不清重点

刚开始项目里很多规范都没有统一，ESLint 一打开全是报错，根本没法工作。

解决方式：先启用基本规则，逐步完善团队编码风格，不要一开始就追求完美。可以在 .eslintrc.js 里先简化配置：

module.exports = {
  extends: ['react-app', 'prettier'],
  parserOptions: {
    ecmaVersion: 2021,
  },
  rules: {
    // 后续逐步补充
  }
}

🧱 4. Ant Design 样式加载不出来 or 主题定制失败

如果你要用主题变量覆盖默认样式，一定要检查是否正确配置了 Less loader。

我们后来放弃了自己配置，改用了社区封装好的 craco 来定制 CRA 项目：

npm install @craco/craco -D

然后新建 craco.config.js：

module.exports = {
  style: {
    css: {
      loaderOptions: {
        url: false,
      },
    },
    sass: {},
    postcss: {},
  },
};

接着你可以放心使用 Less 文件进行变量覆盖：

@import '~antd/lib/style/color/palette.less';
@primary-color: #ff5252;

@border-radius-base: 8px;

🧱 5. 开发环境热更新卡顿，影响效率

CRA 默认开启了热更新，但如果项目中有大量文件变动（比如频繁修改 CSS 或组件结构），会导致频繁重编译，变得越来越慢。

优化建议：

• 分包打包：把第三方库和业务代码分开（code splitting）
• 使用懒加载路由：配合 React.lazy + Suspense
• 减少不必要的 console.log 输出

---

实施效果和收益

最终我们的 CMS 后台顺利上线，虽然只是 MVP 版本，但在以下几个方面带来了显著提升：

• 开发效率提高了约 30%：得益于 React 的组件复用机制
• 团队新人适应周期缩短：清晰的项目结构降低了学习门槛
• 页面性能良好：通过懒加载和合理拆分，首次加载时间控制在 2s 内
• 扩展性强：后续新增模块非常方便，几乎不需要重新设计结构

最重要的是，我们在实战中掌握了 React 的核心开发流程和一些高级技巧，为后面接手更大的项目打下了坚实基础。

---

给你的几点建议：避免我走过的弯路

1. 别一开始就想大而全的架构
   很多同学喜欢上来就配 Webpack、Redux、MobX……但对于新手来说，会把自己搞崩溃。先把功能跑通再说。

2. 学会借助社区的力量
   CRA、Ant Design、DayJS、React Hook Form……这些成熟的工具可以让你节省大量时间，不要重复造轮子。

3. 合理使用调试工具
   Chrome DevTools + React DevTools 插件是你的好伙伴，尤其是调试组件状态、父子传参等问题时，简直是救命稻草。

4. 关注性能与体验细节
   即使是一个内部系统，也要重视 loading 动画、按钮禁用状态、表单验证提示等交互细节，这对用户体验有巨大影响。

5. 持续优化代码质量
   引入 ESlint、Prettier、TypeScript 并非一蹴而就，而是循序渐进。建议从基础规范开始，逐步推进工程化建设。

---

结语：React 学习没有捷径，只有动手去写

回过头来看，我们当初那个小小的内容管理系统项目，其实一点都不起眼，但它却是我们迈入 React 世界的第一步。

现在我们团队已经完成了三个基于 React 的项目，也在不断尝试新的状态管理工具（如 Zustand）、构建工具（Vite）、组件设计系统等等。但不管未来用什么工具，掌握 React 的底层思想才是最关键的。

如果你正准备入门 React，不妨照着本文的步骤自己动手做一遍，哪怕只是一个小小的 demo，也好过读十篇教程。真正的成长，永远来自于实战。

希望你能在 React 的道路上越走越远，少踩坑，多收获！

---

作者简介：前端开发工程师一枚，经历过从 jQuery 到 Vue 再到 React 的完整进化过程。目前专注于中后台系统研发、团队协作与技术落地。欢迎留言交流，共同成长！