React.js 新手入门：环境搭建与第一个组件开发

作者：组件日常时间：2026-11-03 19:40:05浏览：377

面向初学者的 React.js 实用入门指南。从 Node.js 环境检查与 Vite 脚手架创建项目开始，详细解析 React 工程目录与模块挂载机制，带你一步步编写第一个支持 Props 传递与状态交互的函数组件。

图 0：React.js 环境搭建与组件开发全流程概览

学习 React.js 的关键在于建立清晰的工程直觉。本文直接面向新手开发场景，按照“安装运行时依赖 → 使用现代工具链 Vite 初始化项目 → 梳理入口文件挂载逻辑 → 编写并验证第一个可交互自定义组件”的实际操作顺序展开，帮助你在本地快速跑通第一个完整的 React 应用。

一、基础环境准备：Node.js 安装与验证

React 核心是一个用于构建用户界面的 JavaScript 库。在现代前端开发中，我们需要借助于 Node.js 提供的本地运行环境以及 npm（Node Package Manager）包管理器来下载依赖、编译 JSX 语法并启动本地开发服务器。

开始搭建之前，必须确认本地计算机已经安装了 Node.js（推荐使用官方长期支持版本 LTS，如 v18 或 v20 及以上版本）。

1. 检查本地环境命令

打开操作系统的终端（macOS / Linux 用户使用 Terminal，Windows 用户建议使用 PowerShell 或 Windows Terminal），依次执行以下两行命令：

node -v
npm -v

预期输出示例：

v20.11.0
10.2.4

注意事项：如果终端提示 command not found 或类似无法识别命令的信息，说明 Node.js 尚未安装或未加入系统环境变量 PATH。请前往 Node.js 官方网站下载安装包并完成安装，安装完成后重新打开终端进行检测。

图 1：从开发环境准备到本地服务器成功运行的四个关键步骤

二、构建 React 项目：使用 Vite 快速初始化

过去社区常用 create-react-app（CRA）搭建环境，但 CRA 内部基于传统的 Webpack 打包方案，启动慢、构建体积大，目前官方已不再推荐使用。对于新手，当前业内最标准且轻量高效的起步方式是采用 Vite。

Vite 基于浏览器原生 ES 模块（ESM），具备毫秒级的冷启动速度与极快的模块热替换（HMR）能力，配置简明，让初学者能将精力集中在 React 语法本身。

1. 执行项目生成命令

在终端中选择一个存放代码的工作目录，执行以下命令创建一个名为 my-react-app 的工程：

npm create vite@latest my-react-app -- --template react

此命令会直接使用 Vite 官方提供的 React JavaScript 模板生成文件。命令执行过程只需数秒，完成后终端会输出提示信息：

Done. Now run:

  cd my-react-app
  npm install
  npm run dev

2. 进入目录并安装依赖

脚手架生成的文件只包含工程模版与配置说明，核心的 react 和 react-dom 库尚未下载到本地。需要切换到项目目录并执行安装命令：

cd my-react-app
npm install

该命令会读取 package.json 中列出的依赖项，并将编译构建所需的所有包下载到生成的 node_modules 目录中。

3. 启动开发服务器并验证结果

依赖安装完成后，在同一目录下执行：

npm run dev

终端中会出现类似如下的本地开发地址信息：

  VITE v5.x.x  ready in 280 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

按住键盘 Ctrl 键并单击链接（或在浏览器地址栏手动输入 http://localhost:5173/）。如果你在浏览器中看到了带有 Vite 与 React 旋转图标、包含一个可点击计数器按钮的默认欢迎页面，说明你的本地 React 工程环境已经完全搭建成功。

三、项目结构剖析与渲染链路

在开始写自己的组件之前，先打开刚刚生成的 my-react-app 文件夹，了解各个核心文件的分工及其在页面加载时的调用次序。

图 2：Vite-React 项目核心文件结构与组件树装配流程

整个页面的渲染链路非常清晰，主要由以下三个文件串联而成：

index.html：单页应用（SPA）的宿主 HTML 文件。其主体部分只有一个 <div id="root"></div>，底部的 <script type="module" src="/src/main.jsx"></script> 负责载入 JavaScript 入口文件。
src/main.jsx：客户端渲染入口。使用 React 18+ 提供的 ReactDOM.createRoot() 方法找到 index.html 中的 #root 节点，并将根组件 <App /> 渲染进真实 DOM 中。
src/App.jsx：根组件。所有的自定义子组件、页面布局和业务逻辑，最终都直接或间接组合在这个组件中输出。

四、编写你的第一个 React 自定义组件

React 的核心理念是组件化（Component-Based）。一个组件在现代 React 中就是一个普通的 JavaScript 函数，它接收被称为 props 的输入属性，并返回描述 UI 样貌的 JSX 元素。

为了具体掌握组件的编写方法，我们将在项目中创建一个“用户卡片”组件（UserCard）。该组件具备以下功能：

接收父组件传入的用户姓名（name）与岗位职责（role）；
内部维护一个“点赞 / 互动计数”（likes）状态，读者点击按钮时数值实时递增；
利用 JSX 语法将属性与交互状态完整呈现在卡片视图中。

1. 新建组件文件：`src/components/UserCard.jsx`

在项目的 src 目录下新建一个名为 components 的文件夹，并在其中创建 UserCard.jsx，填入以下完整代码：

import { useState } from 'react';

// 自定义函数组件：组件名称首字母必须大写
export function UserCard({ name, role }) {
  // 定义内部响应式状态：likes 代表当前点赞数，setLikes 是更新函数
  const [likes, setLikes] = useState(0);

  // 处理点击交互
  const handleLike = () => {
    setLikes(likes + 1);
  };

  return (
    <div style={{
      border: '1px solid #D1DCE5',
      borderRadius: '8px',
      padding: '16px 20px',
      margin: '12px 0',
      backgroundColor: '#F8FAFC',
      display: 'flex',
      justifyContent: 'space-between',
      alignItems: 'center'
    }}>
      <div>
        <h4 style={{ margin: '0 0 6px 0', color: '#456581' }}>{name}</h4>
        <p style={{ margin: 0, color: '#64748B', fontSize: '14px' }}>岗位：{role}</p>
      </div>
      <button 
        onClick={handleLike}
        style={{
          backgroundColor: '#438A80',
          color: '#FFFFFF',
          border: 'none',
          borderRadius: '4px',
          padding: '8px 14px',
          cursor: 'pointer',
          fontSize: '13px'
        }}
      >
        👍 赞 ({likes})
      </button>
    </div>
  );
}

图 3：JSX 声明式结构、Props 传参与 State 响应机制分解

2. 在根组件中引入并装配 `UserCard`

完成子组件编写后，打开 src/App.jsx。将原先 Vite 生成的默认代码清空，替换为装配我们自定义卡片的代码：

import { UserCard } from './components/UserCard';

function App() {
  // 模拟业务数据列表
  const users = [
    { id: 1, name: '张三', role: '前端架构师' },
    { id: 2, name: '李四', role: 'UI 设计师' },
    { id: 3, name: '王五', role: '后端开发工程师' },
  ];

  return (
    <div style={{ maxWidth: '600px', margin: '40px auto', fontFamily: 'sans-serif' }}>
      <h2 style={{ color: '#456581', borderBottom: '2px solid #E2E8F0', paddingBottom: '10px' }}>
        团队成员展示面板
      </h2>
      <p style={{ color: '#64748B', fontSize: '14px' }}>
        以下卡片均为复用 UserCard 组件渲染，支持独立点击点赞计数：
      </p>

      {/* 使用数组 map 方法循环渲染组件列表 */}
      {users.map((user) => (
        <UserCard 
          key={user.id} 
          name={user.name} 
          role={user.role} 
        />
      ))}
    </div>
  );
}

export default App;

3. 浏览器验证结果

保存文件后，回到此前打开的浏览器窗口 http://localhost:5173/。因为 Vite 具备热更新机制，页面会自动更新出“团队成员展示面板”，包含三张整齐排列的用户卡片。

尝试分别点击不同卡片上的“赞”按钮，你会发现：每个卡片的计数器能够各自独立递增，互不干扰。这说明你的第一个 React 函数组件不仅成功完成了属性传递（Props），还成功实现了独立的局部状态管理（State）。

五、新手开发常见问题与排查方法

常见现象 / 报错	根本原因	针对性解决方案
Adjacent JSX elements must be wrapped	组件 return 中输出了两个并列的标签，违反了 JSX 单根元素限制。	在最外层使用空标签 `<>...</>`（即 `React.Fragment`）将它们包裹起来。
Each child in a list should have a unique "key" prop	使用 `.map()` 遍历渲染列表元素时，未给最外层标签提供唯一的 `key` 属性。	为组件添加唯一的标识属性，如 `key={user.id}`，帮助 React 准确识别 DOM 变更项。
点击按钮时页面立即报错或死循环	误将 `onClick={handleLike}` 写成了 `onClick={handleLike()}`。	事件绑定时必须传入函数引用本身（或箭头函数 `() => handleLike()`），而不是直接调用。
开发环境下组件内 console.log 打印了两次	`main.jsx` 中默认启用了 `<React.StrictMode>`（严格模式）。	这是 React 在开发环境下特意执行的双重调用机制，用以帮助检测潜在副作用，生产构建时会自动关闭。