第2章项目初始化

第2章：项目初始化——从零开始搭架子

好，咱们正式开始动手了。

项目初始化，说白了就是给项目「办个出生证明」。这一步看似简单，但很多人栽在起跑线上。我见过不少团队，项目跑了大半年，连 package.json 里写的啥都说不清楚。嗯，这不行。

2.1 用 npm/yarn/pnpm 初始化项目

先说说工具选择。我个人习惯用 pnpm，原因很简单：快，省磁盘。但如果你刚入门，用 npm 也没问题，它最普及。

初始化命令长这样：

# 用 npm
npm init -y

# 用 yarn
yarn init -y

# 用 pnpm
pnpm init -y

加 -y 参数的意思是「一路默认」，省得你一个个回车。我刚开始学的时候，傻乎乎地一个个填，后来发现大部分字段后面都要改，何必呢？

小技巧： 如果你用 pnpm，建议先全局装一下：npm install -g pnpm。装完之后你会发现，安装依赖的速度真的快了一个量级。

执行完命令，你会看到项目根目录多了一个 package.json 文件。这就是项目的「身份证」。

2.2 理解 package.json——项目的户口本

打开 package.json，你会看到类似这样的内容：

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

每个字段都有它的用途。我挑几个重点说说：

字段	作用	我的建议
`name`	项目名称，发布到 npm 时用	小写+短横线，比如 `my-awesome-tool`
`version`	版本号，遵循 semver 规范	从 `0.1.0` 开始，别上来就 `1.0.0`
`scripts`	定义可执行的命令	这是最常用的字段，后面会频繁修改
`dependencies`	生产环境依赖	运行时必须的库放这里
`devDependencies`	开发环境依赖	构建工具、测试框架放这里

  重点： dependencies 和 devDependencies 的区别一定要搞清楚。我曾经见过一个项目，把 webpack 装到了 dependencies 里，结果生产环境打包时多了一堆没用的代码。说白了，运行时需要的才放 dependencies，开发工具放 devDependencies。

还有一个字段容易被忽略——private。如果你不想项目被意外发布到 npm，加上这个：

"private": true

嗯，这个习惯我建议你从一开始就养成。

2.3 配置 .gitignore——别把垃圾提交上去

项目初始化后，第一件事就是创建 .gitignore 文件。为什么？因为你不希望把 node_modules、.env 这类文件提交到 Git 仓库里。

我见过最惨的一次：有人把 node_modules 提交了，结果仓库体积直接飙到 200MB，同事拉代码等了半小时。从那以后，我每次新建项目第一件事就是配 .gitignore。

一个前端项目标准的 .gitignore 长这样：

# 依赖目录
node_modules/

# 构建输出
dist/
build/
*.tsbuildinfo

# 环境变量
.env
.env.local
.env.*.local

# IDE 配置
.vscode/
.idea/
*.swp
*.swo

# 系统文件
.DS_Store
Thumbs.db

# 日志
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# 测试覆盖率
coverage/

# 临时文件
.tmp
.temp

注意： 如果你用了 pnpm，记得加上 .pnpm-store/。这个目录是 pnpm 的全局缓存，体积很大，千万别提交。

配置好之后，建议先跑一次 git status 检查一下。看看有没有不该出现的文件被列出来。如果有，说明 .gitignore 没写全。

2.4 避坑指南——我踩过的那些坑

讲几个我亲身经历过的坑，你遇到了可以少走弯路：

坑一： 我曾经把 package-lock.json 加到 .gitignore 里。结果团队成员安装的依赖版本不一致，线上出了诡异的 bug。记住，lock 文件一定要提交！
坑二： 有次我忘了加 .env 到 .gitignore，结果把数据库密码提交上去了。虽然及时撤回，但想想都后怕。敏感信息永远不要进仓库。
坑三： 用 npm init -y 生成的 package.json 里 description 是空的。我建议你随手填一句，不然过两个月你自己都忘了这个项目是干嘛的。

我的习惯： 每次初始化项目后，我会先提交一次 chore: init project。这样后续的改动都能追溯到起点。你想想看，如果项目跑了一年，连第一次提交都找不到了，多尴尬。

2.5 小结

项目初始化这一步，说白了就是三件事：

用 npm init 或 pnpm init 生成 package.json
理解 package.json 里每个字段的用途
配好 .gitignore，避免把垃圾文件提交上去

这三件事做完，你的项目才算真正「立住了」。下一章我们聊聊如何配置构建工具，让项目真正跑起来。

📚 课程目录