react 使用Typescript搭建项目

约 1813 字大约 6 分钟

2026-01-27

你想要一份用 TypeScript 搭建 React 项目的完整教程，我依然会讲解两种主流方式（Create React App + TS 快速上手、Vite + React + TS 高效构建），步骤清晰，新手跟着操作就能成功，且全程围绕 TypeScript 配置。

前置准备（必做，和之前一致）

首先必须安装 Node.js（附带 npm 包管理器），这是搭建 React + TS 项目的基础：

下载地址：Node.js 官方下载，选择 LTS 版本（稳定无坑）。
安装验证：打开终端，输入以下命令，能显示版本号即安装成功：
```
node -v
npm -v
```
（可选优化）更换 npm 国内镜像源，避免依赖下载超时：
```
npm config set registry https://registry.npmmirror.com/
```

方式一：Create React App（CRA）+ React + TypeScript（快速上手，官方传统方案）

Create React App 内置了完善的 TypeScript 支持，无需手动配置编译环境，适合新手快速搭建 React + TS 项目，无需关心底层细节。

步骤 1：创建 React + TS 项目

终端输入以下命令（项目名称可自定义，建议小写、无空格、用连字符分隔，例如 my-react-ts-cra）：

# npx 直接调用，无需全局安装 create-react-app
npx create-react-app my-react-ts-cra --template typescript

说明：--template typescript 是核心参数，指定项目模板为 TypeScript，会自动生成 TS 相关配置文件（tsconfig.json、react-app-env.d.ts 等）。

步骤 2：进入项目目录

项目创建完成后（自动安装依赖，无需额外执行 npm install），输入命令进入项目文件夹：

cd my-react-ts-cra

步骤 3：启动开发服务器

输入以下命令启动本地开发环境，支持热更新：

npm start

步骤 4：访问项目

启动成功后，浏览器会自动打开 http://localhost:3000/，若未自动打开，可手动复制该地址访问，就能看到 React + TS 的默认欢迎页面。

补充：CRA + TS 项目核心命令

# 启动开发环境
npm start

# 打包生产环境静态文件（输出到 build/ 目录，可部署到服务器）
npm run build

# 运行单元测试（集成 Jest + TS 支持）
npm test

# 弹出底层配置（Webpack、Babel 等，一旦弹出无法回退，新手不建议操作）
npm run eject

核心 TS 配置文件说明（新手了解即可）

tsconfig.json：TypeScript 项目的核心配置文件，指定编译目标、模块规范、文件包含/排除规则等，CRA 已做默认优化，无需手动修改。
react-app-env.d.ts：CRA 专属的 TS 类型声明文件，用于识别 React 项目中的静态资源（如图片、CSS 文件等），无需修改内容，保留即可。

方式二：Vite + React + TypeScript（高效构建，推荐生产/大型项目）

Vite 对 TypeScript 有原生支持，编译速度远快于 CRA（基于 Webpack），且默认生成更简洁的 TS 配置，热更新效率极高，是当前 React + TS 项目的主流选择，尤其适合大型项目。

步骤 1：创建 Vite + React + TS 项目

终端输入以下命令，调用 Vite 初始化项目：

npm create vite@latest

步骤 2：交互式配置项目（核心是选择 TypeScript 变体）

执行命令后，终端出现交互式选项，新手参考以下选择即可：

Project name：输入项目名称（如 my-react-ts-vite），或直接回车使用默认值 vite-project，回车。
Select a framework：选择框架，用上下箭头选中 React（或直接输入 react），回车。
Select a variant：选择项目变体，这是核心步骤，选中 TypeScript（或直接输入 typescript），回车（如需支持 React 官方的 JSX 转换，也可选择 TypeScript + SWC，效率更高）。

步骤 3：进入项目目录并安装依赖

配置完成后，按照终端提示执行以下命令：

# 进入项目目录（替换为你的项目名称）
cd my-react-ts-vite

# 安装项目依赖（Vite 不会自动安装依赖，需手动执行）
npm install

步骤 4：启动开发服务器

依赖安装完成后，输入以下命令启动本地开发环境：

npm run dev

步骤 5：访问项目

启动成功后，终端会显示访问地址（通常是 http://localhost:5173/ 或 http://127.0.0.1:5173/），复制地址打开浏览器，即可看到 Vite + React + TS 的默认项目页面。

补充：Vite + TS 项目核心命令

# 启动开发环境（热更新速度极快）
npm run dev

# 打包生产环境静态文件（输出到 dist/ 目录）
npm run build

# 预览打包后的项目（本地验证部署效果，无需上传服务器）
npm run preview

核心 TS 配置文件说明（新手了解即可）

tsconfig.json：Vite 生成的 TS 配置文件更简洁，已预设适配 React 和 Vite 的编译规则，新手初期无需修改，后续有特殊需求（如修改编译目标、添加类型声明）再调整即可。

项目核心目录说明（React + TS 专属，新手重点关注）

两种方式创建的项目，核心源代码都在 src/ 目录下，TS 项目和 JS 项目的核心区别是文件后缀为 .tsx（包含 React 组件/JSX 语法）和 .ts（纯 TypeScript 逻辑文件），重点关注：

src/App.tsx：根组件，项目的核心页面结构写在这里，TS 会自动校验组件的 props、返回值等类型。
src/main.tsx（Vite）/ src/index.tsx（CRA）：项目入口文件，负责将 React 组件挂载到 DOM 节点上，是 TS 项目的启动入口。
src/components/（可选，需自己创建）：存放公共可复用组件，如 Button.tsx、Card.tsx，TS 能保证组件复用的类型安全性。
public/：存放静态资源（图片、favicon 图标等），打包后会完整复制到输出目录。

简单测试：验证 TypeScript 类型校验

为了让你直观感受到 TS 的作用，我们可以做一个简单测试（以 App.tsx 为例）：

打开 src/App.tsx，找到默认的组件代码，添加一个带类型约束的变量：

import { useState } from 'react';
import './App.css';

function App() {
  // 定义一个数字类型的变量，TS 会校验其赋值类型
  const [count, setCount] = useState<number>(0);

  return (
    <div className="App">
      <header className="App-header">
        <p>计数：{count}</p>
        <button onClick={() => setCount(count + 1)}>点击加 1</button>
        {/* 尝试给数字类型的 count 赋值字符串，TS 会直接报错（红色波浪线） */}
        {/* <button onClick={() => setCount('abc')}>错误测试</button> */}
      </header>
    </div>
  );
}

export default App;

若你尝试解开注释中的错误代码，TS 会立即在编辑器中提示类型错误，阻止你写出不符合类型约束的代码，这就是 TS 的核心价值——静态类型校验，提前规避运行时错误。

总结

搭建 React + TS 项目的核心是在创建项目时指定 TypeScript 模板/变体，无需手动配置复杂的编译环境。
新手快速上手选 CRA + TypeScript，命令简单、零配置；追求高效构建选 Vite + React + TypeScript，启动和热更新速度更优。
核心要点：CRA 项目用 --template typescript 参数，Vite 项目在变体选择中选 TypeScript，项目核心文件后缀为 .tsx（含 JSX）和 .ts（纯逻辑），TS 会自动进行类型校验。