第3回：创建Express项目 - 学习笔记

学习日期: 2025年6月15日
学习状态: 🚀 学习中

🎯 本回学习目标

  • 理解Express框架的作用
  • 掌握Express项目生成器的使用
  • 学会创建标准的Express项目结构
  • 理解npm命令的各个参数含义

📦 npm命令详解

核心命令分析：npm i -g express-generator@4

🔍 命令拆解

1
2
3
4
5
6

npm i -g express-generator@4
│   │ │  │                └── 版本号：指定安装4.x版本
│   │ │  └── 包名：Express项目生成器
│   │ └── 全局安装标志
│   └── install的简写
└── Node Package Manager

各部分详细说明

1. npm - Node包管理器
  • 全称: Node Package Manager
  • 作用: Node.js的官方包管理工具
  • 功能: 安装、管理、发布Node.js包
2. i - install命令的简写 ⭐
  • 完整形式: npm install
  • 简写形式: npm i
  • 作用: 安装指定的npm包
  • 使用频率: 非常高，是最常用的npm命令之一

💡 重要理解: i 就是 install 的缩写，两者完全等价！

  • npm i express = npm install express
  • npm i -g express-generator = npm install -g express-generator
3. -g - 全局安装标志
  • 含义: global（全局）
  • 作用: 将包安装到全局环境，而不是当前项目
  • 效果:
    • 可以在任何位置使用该工具
    • 安装后可以直接在命令行调用

全局安装 vs 本地安装对比:

1
2
3
4
5
6
7

# 全局安装（-g）
npm i -g express-generator
# 结果：可以在任何目录运行 express 命令

# 本地安装（无-g）
npm i express-generator  
# 结果：只能在当前项目中使用，需要通过 npx 运行
4. express-generator - 包名
  • 作用: Express应用程序生成器
  • 功能: 快速创建Express项目的脚手架工具
  • 安装后可用命令: express
5. @4 - 版本指定
  • 语法: @版本号
  • 作用: 安装指定版本的包
  • 示例:
    • @4 - 安装4.x的最新版本
    • @4.18.0 - 安装具体的4.18.0版本
    • 不写版本号 - 安装最新版本

🛠️ 开发工具技巧

VS Code实用快捷键 ⭐

快速打开终端

1

Ctrl + `（反引号）
  • 作用: 快速打开/关闭VS Code内置终端
  • 优势:
    • 无需鼠标操作，提高开发效率
    • 终端直接在编辑器下方，便于查看代码和运行命令
    • 支持多个终端标签页
  • 使用场景:
    • 运行npm命令
    • 执行git操作
    • 启动开发服务器
    • 调试和测试

💡 学习心得: 这个快捷键在Node.js开发中特别有用，因为需要频繁使用npm命令！

🛠️ Express项目创建完整流程

📋 五步创建法（标准流程）

第1步：全局安装Express Generator

1

npm i -g express-generator@4
  • 作用: 安装Express项目生成器工具
  • 只需执行一次: 全局安装后可重复使用

第2步：创建项目并进入目录

1

express --no-view clwy-api && cd clwy-api

命令拆解:

  • express - 调用Express生成器
  • --no-view - 不使用视图引擎（纯API项目）
  • clwy-api - 项目名称（可自定义）
  • && - 命令连接符，前一个成功后执行后一个
  • cd clwy-api - 进入刚创建的项目目录

💡 命令技巧: && 让两个命令连续执行，提高效率

第3步：安装项目依赖

1

npm i
  • 作用: 安装package.json中定义的所有依赖包
  • 等同于: npm install（使用简写更高效）
  • 必须在项目目录内执行

第4步：安装开发工具 - nodemon

1

npm i nodemon
  • 作用: 自动重启开发服务器的工具
  • 优势: 代码修改后自动重启，无需手动重启服务器
  • 使用: 代替 npm start 使用 nodemon 启动
  • 开发必备: 大幅提升开发效率

第5步：启动项目

1
2
3

npm start
# 或者使用nodemon（推荐开发时使用）
nodemon
  • npm start: 普通启动，代码修改需手动重启
  • nodemon: 智能启动，代码修改自动重启 ⭐
  • 默认地址: http://localhost:3000/ 🌐
  • 重要提醒: 命令行不会自动显示访问地址，需要手动在浏览器输入

🌐 访问测试

  • 浏览器访问: http://localhost:3000/
  • 预期结果: 看到Express欢迎页面或JSON响应
  • 测试API: http://localhost:3000/users （如果有users路由）

📝 完整操作示例

实际执行记录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 步骤1：安装生成器（仅需一次）
npm i -g express-generator@4

# 步骤2：创建项目并进入目录
express --no-view clwy-api && cd clwy-api

# 步骤3：安装依赖
npm i

# 步骤4：安装开发工具
npm i nodemon

# 步骤5：启动项目（推荐使用nodemon）
nodemon

# 打开浏览器访问：http://localhost:3000/

参数说明详解

--no-view 参数

  • 作用: 创建纯API项目，不包含视图模板
  • 适用场景:
    • RESTful API服务
    • 前后端分离项目的后端
    • 微服务架构
  • 对比: 
    1
2

    express clwy-api           # 包含视图引擎（如Jade/Pug）
express --no-view clwy-api # 纯API项目，无视图

项目名称规范

  • ✅ 推荐: clwy-api, my-express-app, blog-backend
  • ❌ 避免: 中文名称、特殊字符、空格

📁 Express项目结构分析

--no-view 模式生成的目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

clwy-api/
├── bin/
│   └── www              # 启动脚本（服务器配置）
├── public/              # 静态文件目录
│   ├── images/
│   ├── javascripts/
│   └── stylesheets/
├── routes/              # 路由文件
│   ├── index.js         # 主路由 (/)
│   └── users.js         # 用户路由 (/users)
├── app.js               # 主应用文件（Express应用配置）
├── package.json         # 项目配置文件
└── package-lock.json    # 依赖版本锁定文件（保证版本一致性）

关键文件说明

  • bin/www: 服务器启动脚本，定义端口3000
  • app.js: Express应用主文件 📝
    • 路由配置
    • 跨域配置
    • 中间件配置
    • 注意: 入门阶段暂时不需要深入分析和修改
  • routes/: API路由定义，实现业务逻辑
  • public/: 静态资源（图片、CSS、JS等）
  • package.json: 项目依赖和脚本配置
  • package-lock.json: 版本锁定文件（确保团队依赖版本一致，入门阶段不用关注）

💡 学习建议:

  • 重点关注：routes/ 目录，这是业务逻辑的核心
  • 暂时跳过：app.js 和 package-lock.json 的详细分析
  • 循序渐进：基础掌握后再深入配置文件

💡 npm命令常用简写对照表

完整命令 简写 作用
npm install npm i 安装包
npm install --save npm i -S 安装并保存到dependencies
npm install --save-dev npm i -D 安装并保存到devDependencies
npm install --global npm i -g 全局安装
npm uninstall npm un 卸载包
npm update npm up 更新包
npm list npm ls 查看已安装包

🎯 实践练习记录

练习1：理解命令结构

  • 分析 npm i -g express-generator@4 各部分含义
  • 理解 i 是 install 的简写
  • 掌握全局安装和本地安装的区别

练习2：开发环境技巧

  • 掌握 `Ctrl + `` 快速打开VS Code终端
  • 在内置终端中测试npm命令
  • 熟练使用终端进行开发操作

练习3：安装Express Generator

  • 使用 `Ctrl + `` 打开终端
  • 确保当前路径为纯英文目录 ⚠️
  • 执行安装命令：npm i -g express-generator@4
  • 验证安装成功：express --version

练习4：创建Express项目（完整流程）

  • 第1步: 全局安装 npm i -g express-generator@4
  • 第2步: 创建项目 express --no-view clwy-api && cd clwy-api
  • 第3步: 安装依赖 npm i
  • 第4步: 安装nodemon npm i nodemon
  • 第5步: 启动项目 nodemon（或 npm start）
  • 第6步: 浏览器访问 http://localhost:3000/
  • 第7步: 如果要返回JSON而不是HTML，删除 public/index.html 🔧
  • 记录整个过程和遇到的问题

🤔 学习疑问与解答

Q: 为什么要全局安装express-generator？

A: 因为express-generator是一个脚手架工具，需要在任何位置都能使用express命令来创建新项目。如果本地安装，只能在特定项目中使用。

Q: 不指定版本号会怎样？

A: 会安装最新版本。指定@4是为了保证课程的一致性，避免版本差异导致的问题。

Q: 如果忘记加-g会怎样？

A: 包会安装到当前目录的node_modules中，无法直接使用express命令，需要用npx express来运行。

⚠️ 重要注意事项与踩坑记录

🚨 项目路径命名规范

❌ 项目目录不能包含中文！

  • 问题: Node.js项目路径包含中文字符会导致各种问题

  • 常见错误示例:

    1
2
3

    ❌ D:\我的项目\express-app
❌ D:\学习资料\Node.js项目\my-app
❌ D:\桌面\新建文件夹\express-demo

  • 正确路径示例:

    1
2
3

    ✅ D:\projects\express-app
✅ D:\dev\nodejs-learning\my-app
✅ D:\workspace\express-demo

可能出现的问题

  1. npm安装依赖失败
  2. 路径解析错误
  3. 构建工具报错
  4. 部署时出现异常

解决方案

  • 项目创建前: 选择纯英文路径
  • 已有中文路径: 将项目移动到英文路径下
  • 建议: 养成使用英文路径的习惯

推荐的项目目录结构

1
2
3
4
5
6
7

D:\
├── dev\              # 开发项目根目录
│   ├── nodejs\       # Node.js项目
│   ├── react\        # React项目
│   └── vue\          # Vue项目
├── projects\         # 个人项目
└── learning\         # 学习项目

Web服务器文件优先级问题

问题现象

  • 情况: 修改了 routes/index.js 中的路由逻辑，但浏览器仍显示HTML页面而不是JSON数据
  • 原因: Express静态文件服务器遵循默认文件优先级规则

🎯 核心原理：Web服务器文件优先级

大多数Web服务器（Apache、Nginx、Express静态服务器等）的默认文件查找优先级：

1
2
3
4
5

1. index.html    ← 最高优先级
2. index.htm
3. index.js      ← 路由文件
4. index.php
5. 其他...

🔄 问题解析过程

  1. 访问根路径 http://localhost:3000/

  2. Express检查顺序:

    • 首先查找 public/index.html （如果存在）
    • 找到HTML文件 → 直接返回静态HTML
    • 不会执行 routes/index.js 中的路由逻辑

  3. 结果: 看到的是静态HTML页面，而不是API返回的JSON

⚡ 解决方案

删除静态HTML文件:

1
2
3
4

# 删除public目录下的index.html
rm public/index.html
# 或者重命名
mv public/index.html public/index.html.bak

删除后的效果:

  • Express找不到 index.html
  • 继续查找路由处理 routes/index.js
  • 正确返回JSON数据

💡 深入理解

1
2
3
4

// routes/index.js 路由逻辑示例
router.get('/', function(req, res, next) {
  res.json({ message: 'Hello API!' }); // 返回JSON数据
});

当存在 public/index.html 时:

  • 访问 / → 返回HTML文件内容
  • 路由逻辑被跳过

删除 public/index.html 后:

  • 访问 / → 执行路由逻辑 → 返回JSON: {"message": "Hello API!"}

🛠️ 最佳实践建议

  1. API项目: 删除或移除 public/index.html
  2. 全栈项目: 根据需求决定是否保留静态文件
  3. 开发调试: 了解静态文件和路由的优先级关系
  4. 文档记录: 在项目README中说明文件结构和访问规则

💡 重要提醒: 这不是Express的BUG，而是Web服务器的标准行为！理解这个机制对Web开发很重要。

📝 学习心得

今天的重要收获

  1. npm简写命令: npm i 就是 npm install 的简写，大大提高输入效率
  2. 全局安装概念: -g 参数让工具在任何位置都可用
  3. 版本控制: @版本号 语法确保安装特定版本，避免兼容性问题
  4. VS Code效率技巧: `Ctrl + `` 快速打开终端，Node.js开发必备！⭐
  5. 路径规范: 项目目录绝对不能包含中文，这是重要的踩坑经验！🚨
  6. 五步创建法: 掌握了Express项目的标准创建流程（含nodemon）
  7. 命令连接: && 可以连接多个命令，提高操作效率
  8. 默认端口: Express项目默认运行在3000端口，需要手动访问测试
  9. 文件优先级: 理解了Web服务器的文件查找优先级机制 🔍
  10. 静态文件vs路由: 学会了如何处理静态文件和路由冲突问题
  11. 开发工具: nodemon自动重启功能，提升开发效率 ⚡
  12. 配置文件: 了解app.js的作用，但入门阶段先不深入分析

实用开发技巧总结

  • 终端快捷键: `Ctrl + `` - 比手动点击终端按钮快很多
  • npm简写: npm i 代替 npm install - 减少打字量
  • 路径选择: 始终使用纯英文路径 - 避免各种莫名其妙的错误
  • 命令组合: 在VS Code终端中直接运行npm命令，无需切换窗口
  • 连续执行: && 连接符让命令顺序执行，一气呵成
  • 默认地址: 记住 http://localhost:3000/ 是Express默认访问地址

关键命令速查 🔖

1
2
3
4
5
6
7

# Express项目五步创建法
npm i -g express-generator@4              # 1. 安装工具
express --no-view clwy-api && cd clwy-api # 2. 创建项目并进入
npm i                                      # 3. 安装依赖
npm i nodemon                              # 4. 安装开发工具
nodemon                                    # 5. 启动项目（推荐）
# 然后访问: http://localhost:3000/

开发vs生产启动对比

1
2
3
4
5

# 开发环境（推荐）
nodemon          # 自动重启，代码修改立即生效

# 生产环境
npm start        # 普通启动，稳定运行

踩坑避免清单 ⚠️

  • ❌ 项目路径包含中文字符
  • ❌ 忘记添加 -g 参数进行全局安装
  • ❌ 拼写错误（如 avalable 而不是 available）
  • ❌ 不了解静态文件优先级，导致路由被覆盖 🚨
  • ✅ 使用纯英文项目路径
  • ✅ 熟练使用VS Code快捷键提高效率
  • ✅ 理解Web服务器文件优先级机制
  • ✅ API项目应删除默认的index.html文件

下次学习重点

  • 深入了解Express框架基础概念
  • 学习Express路由系统
  • 理解中间件的概念和使用

笔记更新时间: 2025年6月15日
下次复习时间: ___________