项目初始化与工程结构设计

说实话，很多新手做项目时，上来就写代码。写到一半发现目录乱成一锅粥，测试文件不知道放哪，配置文件散落一地。我早期也踩过这个坑，后来才明白——好的工程结构，比好的代码更重要。

这一章，我们就来聊聊怎么用 npm init 创建一个规范的前端项目，以及目录结构该怎么规划。你想想看，一个清晰的项目骨架，能让你少走多少弯路？

3.1 用 npm init 创建项目

先打开终端，找个空目录，执行：

mkdir design-spec-checker
cd design-spec-checker
npm init -y

-y 参数的意思是「一路默认」。我个人习惯先用这个快速生成，后面再手动改 package.json。为什么？因为省时间，而且默认值基本够用。

执行完后，你会看到一个 package.json 文件。嗯，这里要注意，name 字段不能有中文或大写字母，否则后面发布或安装依赖时会报错。我曾经有个同事，项目名写了个大写字母，结果 CI 流程跑了一整天没通过，最后发现是这个问题。

接下来，我们手动调整一下 package.json：

{
  "name": "design-spec-checker",
  "version": "1.0.0",
  "description": "前端设计规范检查工具",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "test": "jest",
    "lint": "eslint src/"
  },
  "keywords": ["design", "spec", "checker"],
  "author": "你的名字",
  "license": "MIT"
}

这里我加上了 scripts 字段。说白了，这就是项目的「快捷指令」。以后你只需要 npm run test 就能跑测试，不用每次都敲一长串命令。

3.2 目录结构规划

项目初始化完了，接下来是重头戏——目录结构。我见过太多项目，src 下面堆了上百个文件，没有分类，没有层次。找文件全靠搜索，维护起来简直噩梦。

我个人推荐的结构是这样的：

design-spec-checker/
├── src/                # 源代码
│   ├── index.js        # 入口文件
│   ├── core/           # 核心逻辑
│   │   ├── parser.js   # 解析器
│   │   └── checker.js  # 检查器
│   ├── rules/          # 规则定义
│   │   ├── color.js    # 颜色规范
│   │   └── font.js     # 字体规范
│   └── utils/          # 工具函数
│       └── helpers.js
├── config/             # 配置文件
│   ├── default.json    # 默认配置
│   └── custom.json     # 用户自定义配置
├── test/               # 测试文件
│   ├── core/
│   │   └── checker.test.js
│   └── rules/
│       └── color.test.js
├── docs/               # 文档
│   └── README.md
├── .eslintrc.js        # ESLint 配置
├── .gitignore          # Git 忽略文件
└── package.json

你可能会问：为什么要把 config 单独拎出来？因为配置和代码分离，是工程化的基本原则。我在项目中遇到过，有人把配置硬编码在代码里，结果换了个环境就得改代码，非常痛苦。

3.3 各目录的职责说明

我们来逐个拆解一下每个目录的职责：

目录	职责	典型文件
src/	存放所有源代码，按功能模块拆分	index.js, parser.js
config/	存放项目配置，支持多环境	default.json, custom.json
test/	存放单元测试和集成测试	checker.test.js
docs/	存放项目文档，如 README、API 文档	README.md
node_modules/	依赖包目录，由 npm 自动生成	无需手动管理

这里要特别强调一下 test/ 目录。很多初学者喜欢把测试文件和源码混在一起，比如 src/utils/helpers.test.js。我个人不建议这样做，因为当项目变大后，源码目录会变得非常臃肿。把测试统一放在 test/ 下，结构更清晰，也方便 CI 工具扫描。

3.4 核心逻辑流程图

为了让你更直观地理解整个项目的结构，我画了一张流程图。它展示了从入口到核心逻辑、规则定义、配置加载的完整链路：

从这张图你可以看到，src/index.js 是入口，它调用 core/ 里的解析器和检查器。检查器需要依赖 rules/ 里的规则定义，同时从 config/ 加载配置。最终输出检查结果。

说白了，这个结构就是「入口 → 核心逻辑 → 规则 + 配置 → 输出」。层次清晰，职责单一。你想想看，如果以后要加一个新规则，只需要在 rules/ 下新建一个文件，然后在配置里注册一下就行，完全不用动核心代码。

3.5 初始化 Git 仓库

项目结构搭好了，别忘了初始化 Git：

git init
echo "node_modules/" >> .gitignore
echo "dist/" >> .gitignore
git add .
git commit -m "项目初始化：搭建基础目录结构"

这里有个细节：.gitignore 一定要在第一次 commit 之前写好。我见过有人先 commit 了，然后发现 node_modules 被提交上去了，又得用 git rm --cached 去删，非常麻烦。

3.6 本章小结

这一章我们做了三件事：

• 用 npm init 创建了项目，并配置了 package.json
• 规划了 src/、config/、test/ 等目录结构
• 初始化了 Git 仓库，并配置了 .gitignore

嗯，这些看起来都是基础操作，但基础往往决定上限。一个好的项目结构，能让你在后续开发中省下大量时间。下一章，我们会开始写真正的代码——实现一个简单的设计规范解析器。

---