第四章：磨刀不误砍柴工 · 搭建开发环境

4.1 一个可能拯救你无数小时的起点

在上一章的末尾，我们说：“先搭好脚手架，大楼才能盖得高。”

你可能已经迫不及待想看到那些元素方块在屏幕上飞了，我完全理解。但请再给我一点点时间。因为在编程的世界里，有一个残酷的真相：你未来80%的抓狂和崩溃，都不是因为你的代码逻辑错了，而可能是你的开发环境没配好。

想象一下，你要画一幅画。你会随便找张皱巴巴的废纸就开始吗？肯定不会。你会先铺好画布，调好颜料，然后再摆好画架。本章要做的，就是为你未来的所有代码，铺好这张平整、干净、专业的“画布”。

我们今天的任务清单如下：

确认 Node.js 已准备就绪。
用 Vite 为我们搭好项目骨架。
引入 TypeScript，给我们的项目代码加上“安全带”。
配置路径别名，告别可怕的 ../../../ 地狱。
跑起来！在浏览器里看到我们的第一个页面。

4.2 第一步：让 Node.js 在你的电脑里住下来

现代前端开发，已经离不开 Node.js 了。它为我们提供了两样至关重要的东西：

npm（Node 包管理器）：一个能够安装、卸载、管理无数第三方代码包（比如 React、Vite）的工具。没有它，我们得自己从各个网站下载代码包，然后手动管理它们之间的依赖关系。
一个JavaScript运行时：它让我们可以直接在终端里执行JS程序，而不是只能在浏览器中。Vite 的构建脚本就是用它来跑的。

如何安装？

我不会在这里贴出一大段安装命令，因为软件的下载链接和安装步骤是会变的。我教你一个通用方法，这个方法能让你学会安装任何工具：

打开你最熟悉的搜索引擎。
输入关键词：Node.js download。
找官网：在搜索结果里，找到网址是 nodejs.org 的那个结果，点进去。“记住，找官网是解决这类问题的第一步”。
下载长期支持版（LTS）：官网首页通常有两个大按钮，一个写着最新版，一个写着LTS。选LTS，它最稳定，问题最少。
安装：下载完成后，双击安装包，一路点“Next”就行。安装程序会自动帮你把环境变量配置好。

验证是否成功

安装完成后，我们需要验证一下。打开你的命令行终端。怎么打开？Windows 上按 Win + R，输入 cmd 回车；Mac 上按 Command + 空格，输入 Terminal 回车。

然后分别输入以下两条命令，如果能正常显示版本号，就说明成功了：

node -v
# 应显示类似 v18.x.x 或 v24.x.x 的版本号
npm -v
# 应显示类似 9.x.x 或 11.x.x 的版本号

npm 会随着 Node.js 一起安装，所以你不需要额外操作。现在，我们的工具箱里已经有了第一个，也是最基础的工具。

4.3 第二步：让 Vite 在三秒钟内，为我们生成一个项目

接下来，我们需要一个工具来帮我们把项目的“骨架”搭起来。这个骨架包括：基本的目录结构、一个能启动的开发服务器、以及一系列默认的配置文件。这个工具，就是 Vite。

你可能会问：“老师，我看网上很多项目都是手动创建文件夹和文件的，为什么我们要用工具？”

问得好。手动创建当然可以，但那就像明明有电钻，你却非要用螺丝刀去钻墙。Vite 这类脚手架工具能帮你做好所有默认的、枯燥的配置工作，让你把精力集中在写代码上，而不是折腾配置文件。善用工具，是专业素养的一部分。

在终端里，我们使用 npm create 命令来调用 Vite 的脚手架：

# 进入你想放项目的目录，比如桌面
cd ~/Desktop

# 用 Vite 创建一个新项目
npm create vite@latest the118-pTable -- --template react-ts

上面这行命令很长，我们把它拆开看看是什么意思：

npm create：这是 npm 提供的创建项目的命令。
vite@latest：告诉 npm，我要用的创建工具是最新版的 Vite。
the118-pTable：这是我们的项目名称，也是文件夹的名字。
--：一个分隔符，后面的参数是传给 Vite 的，而不是传给 npm 的。
--template react-ts：告诉 Vite，我要用 React + TypeScript 的模板。

当你按下回车，Vite 会快速生成一个文件夹，里面装满了文件。然后，它会提示你进行下一步操作。跟着它做就行：

cd the118-pTable    # 进入项目目录
npm install         # 安装所有依赖包
npm run dev         # 启动开发服务器

最后一个命令执行后，你会看到终端出现一行类似这样的信息：

  VITE v8.x.x  ready in 300 ms

  ➜  Local:   http://localhost:5173/

按住 Ctrl（Mac上是 Command）点击那个链接，或者手动在浏览器里输入 http://localhost:5173/。如果一切顺利，你会看到一个旋转的 React 图标，和一行 “Vite + React” 的文字。

恭喜！你的项目已经跑起来了！

我们现在有了一个可以工作的“毛坯房”。虽然它还很简陋，只有四面墙和一个屋顶，但它是完全属于你的。从这一刻起，你可以用 npm run dev 来启动它，打开浏览器边写代码边看效果。这就是所谓的热更新——你改了代码，网页自动刷新，不需要手动按F5。

4.4 第三步：给我们的代码系上“安全带”——配置 TypeScript

我们的项目模板已经自带了 TypeScript，但我们需要确保它“严格”到让我们受不了。

打开项目根目录下的 tsconfig.app.json 文件（这是 Vite 为了区分应用代码和构建工具代码，而拆分的配置文件）。你会看到一堆配置选项。别怕，我们只需要关注几个关键的：

{
  "compilerOptions": {
    // ... 其他选项
    "strict": true,  // 开启所有严格检查
    "noUnusedLocals": true,  // 定义了但没用的变量，报错
    "noUnusedParameters": true,  // 定义了但没用的函数参数，报错
    "noFallthroughCasesInSwitch": true, // 防止 switch 漏写 break
  }
}

"strict": true 是一个“全家桶开关”，它会开启 TypeScript 所有严格的类型检查。这意味着，你不能再把数字当字符串用了，你不能忘记给变量指定类型，你不能随便写一个不存在的属性。

为什么我们要对自己这么狠？

用TypeScript就像开车系安全带。在低速的时候，你感觉它有点勒，不舒服。但当意外来临时，它是唯一能救你的东西。在我们的代码量从100行涨到1000行、10000行时，TypeScript会在我们每一次粗心大意时，给我们亮起红灯，拒绝编译。这些被它拦截下来的错误，就是我们省下来的、未来调试的时间。

4.5 第四步：告别 `../../../` 地狱——配置路径别名

你有没有看到过这样的代码？

import { foo } from '../../../utils/foo';

那些 ../ 就像羊屎蛋子，一路走一路拉，恶心又难缠。当你的文件结构变深，你会发现你总是在数“我到底在第几层？”。

幸好，我们可以用 路径别名（Path Alias） 来一劳永逸地解决这个问题。

我们的目标是什么？就是把那个又长又臭的相对路径，变成一个清爽、绝对不会搞混的绝对路径，比如：

// 原本的样子
import { foo } from '../../../utils/foo';

// 我们想要的样子
import { foo } from '@/utils/foo';

这里的 @ 就是我们定义的别名，它永远指向项目的 src 目录。这样，无论你当前的文件在哪个深度的子目录里，@/ 都指向同一个根，你再也不用去数那些烦人的 ../ 了。

要实现这个魔法，我们需要在两个地方进行配置，让它们都认识 @ 这个符号。

1. 告诉 TypeScript 编译器：@ 就是 src/

打开 tsconfig.app.json，找到 "compilerOptions"，在里面添加 "paths" 配置：

{
  "compilerOptions": {
    // ... 其他配置
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

这句配置的意思是：“嘿，TypeScript，以后你看到以 @/ 开头的路径，就把它当作相对路径 ./src/ 来处理。”这样，在你写代码时，TypeScript 就能正确地找到文件，不会给你报错了。

2. 告诉 Vite 构建器：@ 就是 src/

TypeScript 只是负责在写代码阶段不报错。但真正把代码打包成能在浏览器里运行的文件的，是 Vite。我们还需要告诉 Vite 这个别名规则，否则它会不认识 @/ 而报错。

打开项目根目录下的 vite.config.ts 文件，把它修改成这样：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path';  // 引入 Node.js 的路径处理模块

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      // 将 @ 映射到 src 目录
      '@': path.resolve(__dirname, './src'),
    }
  }
})

这里 path.resolve(__dirname, './src') 会动态地计算出你电脑上 src 文件夹的绝对路径，然后把它赋值给 @。现在，Vite 也认识 @/ 了。

测试一下

为了确保配置生效，我们来做一个小实验。在 src 目录下新建一个文件夹 utils，在里面新建一个文件 test.ts，写一行代码：

// src/utils/test.ts
export const hello = 'Hello, THE118!';

然后，打开 src/App.tsx，在顶部用我们的新别名引入它：

import { hello } from '@/utils/test';
console.log(hello);

保存文件。如果浏览器控制台打印出了 Hello, THE118!，而且编辑器没有任何报错，那就说明我们大功告成了！

本章我们完成了从零到一的开发环境搭建。现在，我们拥有了一个用 Vite 启动的、有 TypeScript 严格检查的、路径清爽的前端项目。它就静静地躺在你的电脑里，等待着我们去赋予它生命。

工欲善其事，必先利其器。工具有了，下一步，我们要学习如何像一个专业的工匠一样，保持我们的工作台（代码）整洁、规范。

从下一章开始，我们将引入一系列约束工具：Git 的代码历史管理、ESLint 的代码风格检查、Commitlint 的提交信息规范。它们会让你感觉有点“被束缚”，但请相信我，正是这些束缚，才能让你在未来的复杂项目中，不至于被自己的代码沼泽所淹没。

Keyboard shortcuts