以下是针对初学者的 Node.js package.json
配置详解 + TypeScript + ES Module 集成指南,用通俗语言、代码示例和场景化说明,帮你快速掌握核心要点:
一、package.json
:Node.js 项目的"控制中心"
package.json
是 Node.js 项目的核心配置文件,记录项目元数据、依赖、脚本等信息。它相当于项目的"说明书",也是 npm/yarn 管理依赖的依据。
二、package.json
常用配置项(通俗版)
1. 基础元数据(项目"名片")
字段 | 作用 | 示例 |
---|---|---|
name |
项目名称(唯一标识,小写+短横线) | "name": "my-ts-esm-app" |
version |
项目版本(语义化版本,如 1.0.0 ) |
"version": "1.0.0" |
description |
项目描述(可选,用于搜索) | "description": "A TypeScript Node.js app with ES Module" |
main |
项目入口文件(Node.js 启动时加载) | "main": "dist/index.js" (编译后的 JS 入口,ES Module 需注意格式) |
keywords |
关键词(可选,用于搜索) | "keywords": ["typescript", "nodejs", "esm"] |
author |
作者信息(格式:姓名 <邮箱> ) |
"author": "张三 <zhangsan@example.com>" |
license |
开源协议(如 MIT、GPL) | "license": "MIT" |
2. 依赖管理(dependencies
与 devDependencies
)
字段 | 作用 | 示例 |
---|---|---|
dependencies |
生产环境依赖(项目运行必需) | "dependencies": { "express": "^4.18.2" } (Express 框架,生产环境需要) |
devDependencies |
开发环境依赖(仅开发/构建时需要) | "devDependencies": { "typescript": "^5.2.2", "ts-node": "^10.9.2" } |
关键区别:
dependencies
:项目上线时必须打包(如 Express、Lodash)。devDependencies
:仅在开发时使用(如 TypeScript 编译器、测试工具 Jest)。
安装命令:
bash
# 安装生产依赖(自动添加到 dependencies)
npm install express --save
# 安装开发依赖(自动添加到 devDependencies)
npm install typescript --save-dev
3. 脚本命令(scripts
:项目的"快捷按钮")
scripts
定义可执行的命令,通过 npm run <命令名>
触发,是开发自动化的核心。
常用脚本示例(含 TypeScript + ES Module):
json
{
"scripts": {
"start": "node dist/index.js", // 启动生产环境(运行编译后的 ES Module JS)
"dev": "ts-node src/index.ts", // 开发环境(直接运行 TS 文件,无需手动编译)
"build": "tsc", // 编译 TS 到 JS(输出到 dist,ES Module 格式)
"build:watch": "tsc --watch", // 监听 TS 文件变化,自动重新编译
"lint": "eslint src/**/*.ts" // 代码检查(需安装 ESLint)
}
}
说明:
npm run dev
:用ts-node
直接运行 TS 文件(适合开发调试)。npm run build
:将 TS 编译为 ES Module 格式的 JS(输出到dist
)。npm run start
:启动生产环境(运行dist
中的编译后文件)。
4. 其他重要配置
字段 | 作用 | 示例 |
---|---|---|
engines |
限制 Node.js/npm 版本 | "engines": { "node": ">=18.0.0", "npm": ">=9.0.0" } (Node.js 18+ 支持 ES Module) |
repository |
代码仓库地址(如 GitHub) | "repository": { "type": "git", "url": "https://github.com/your/repo.git" } |
bugs |
问题反馈链接 | "bugs": { "url": "https://github.com/your/repo/issues" } |
type |
模块系统类型(关键!ES Module 必须) | "type": "module" (所有 .js 文件视为 ES Module) |
三、TypeScript + ES Module 集成(完整示例)
1. 步骤 1:初始化项目并安装依赖
bash
# 创建项目目录并进入
mkdir ts-esm-app && cd ts-esm-app
# 初始化 package.json(一路回车,生成默认配置)
npm init -y
# 安装 TypeScript(开发依赖)
npm install typescript --save-dev
# 安装 Node.js 类型定义(让 TS 识别 Node.js API,开发依赖)
npm install @types/node --save-dev
# 安装 ts-node(直接运行 TS 文件,开发依赖)
npm install ts-node --save-dev
2. 步骤 2:配置 tsconfig.json
(ES Module 关键)
在项目根目录创建 tsconfig.json
,控制 TS 编译器的行为(重点是 ES Module 格式)。
示例 tsconfig.json
(ES Module 版):
json
{
"compilerOptions": {
"target": "ES2020", // 目标 JS 版本(Node.js 14+ 支持 ES Module)
"module": "ESNext", // 模块系统:ESNext(ES Module 最新语法)
"moduleResolution": "NodeNext", // 模块解析:NodeNext(兼容 ES Module 和 CommonJS)
"outDir": "./dist", // 编译输出目录(TS → JS 存放于此)
"rootDir": "./src", // 源码根目录(TS 文件存放于此)
"strict": true, // 严格类型检查(推荐开启)
"esModuleInterop": true, // 兼容 ES 模块和 CommonJS(避免导入问题)
"skipLibCheck": true, // 跳过第三方库类型检查(提升速度)
"resolveJsonModule": true // 支持导入 JSON 文件(可选)
},
"include": ["src/**/*"], // 需要编译的文件(src 目录下所有 TS 文件)
"exclude": ["node_modules"] // 排除 node_modules 目录
}
关键配置说明(ES Module 相关):
module: "ESNext"
:指定编译后的模块语法为 ES Next(支持import/export
)。moduleResolution: "NodeNext"
:让 TS 按 Node.js 最新规则解析模块(兼容 ES Module)。"type": "module"
(在package.json
中):告诉 Node.js 所有.js
文件是 ES Module。
3. 步骤 3:编写 TypeScript 代码(ES Module 示例)
在 src
目录下创建入口文件 index.ts
和工具模块 utils.ts
。
示例 src/utils.ts
(导出模块):
typescript
// 命名导出(多个功能)
export const add = (a: number, b: number): number => a + b;
export const PI = 3.14;
// 默认导出(一个主要功能)
export default function multiply(a: number, b: number): number {
return a * b;
}
示例 src/index.ts
(导入模块并运行):
javascript
// 导入命名导出(需用大括号)
import { add, PI } from './utils.js'; // 注意:TS 编译后是 .js,但开发时用 .ts
// 导入默认导出(无需大括号)
import multiply from './utils.js';
// 使用模块功能
console.log('加法:', add(2, 3)); // 输出 5
console.log('乘法:', multiply(2, 3)); // 输出 6
console.log('圆周率:', PI); // 输出 3.14
// 导出当前模块的内容(可选,若需要被其他模块导入)
export { add };
4. 步骤 4:修改 package.json
以支持 ES Module
在 package.json
中添加 type: "module"
,并完善 scripts
命令:
json
{
"name": "ts-esm-app",
"version": "1.0.0",
"type": "module", // 关键!声明项目使用 ES Module
"main": "dist/index.js", // 入口文件(编译后的 ES Module JS)
"scripts": {
"start": "node dist/index.js", // 启动生产环境
"dev": "ts-node src/index.ts", // 开发环境(直接运行 TS)
"build": "tsc", // 编译 TS 到 ES Module JS
"build:watch": "tsc --watch" // 监听 TS 变化,自动编译
},
"devDependencies": {
"@types/node": "^20.11.7",
"typescript": "^5.3.3",
"ts-node": "^10.9.2"
}
}
5. 步骤 5:运行与测试
(1)开发模式(直接运行 TS 文件)
arduino
npm run dev # 输出:加法:5,乘法:6,圆周率:3.14
(2)生产模式(编译后运行)
arduino
npm run build # 编译 TS 到 dist 目录(生成 index.js 和 utils.js)
npm run start # 运行编译后的 JS 文件(输出同上)
(3)监听模式(自动编译)
修改 src/index.ts
中的代码(如 console.log('加法:', add(5, 5))
),运行:
arduino
npm run build:watch # 自动重新编译,无需手动操作
四、常见问题与避坑指南
1. 报错:"Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'xxx'"
-
原因 :TS 无法识别第三方库的类型定义(如
lodash
)。 -
解决 :安装对应库的类型定义(
@types/xxx
):sqlnpm install @types/lodash --save-dev
2. 报错:"TS2307: Cannot find module './utils' or its corresponding type declarations"
-
原因 :TS 未正确识别自定义模块的路径(如
src/utils.ts
)。 -
解决:
- 确保
tsconfig.json
的rootDir
和include
配置正确(如rootDir: "./src"
)。 - 导入时使用相对路径(如
import { add } from './utils.js'
,注意编译后是.js
)。
- 确保
3. 报错:"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"
-
原因 :在 CommonJS 模块中使用了
require()
导入 ES Module 文件。 -
解决:
- 确保
package.json
中添加了"type": "module"
。 - 所有导入/导出使用
import
/export
语法(而非require
/module.exports
)。
- 确保
4. 编译后的 JS 文件未按 ES Module 格式输出
- 原因 :
tsconfig.json
中的module
配置错误(如设置为CommonJS
)。 - 解决 :检查
tsconfig.json
的module
字段,确保为ESNext
或NodeNext
。
五、总结:关键步骤速查表
步骤 | 操作 |
---|---|
初始化项目 | npm init -y 生成 package.json |
安装依赖 | npm install typescript @types/node ts-node --save-dev |
配置 tsconfig.json |
设置 module: "ESNext" 、rootDir: "./src" 、outDir: "./dist" |
修改 package.json |
添加 "type": "module" ,配置 scripts 支持 dev 、build 等命令 |
编写代码 | 使用 import /export 语法(ES Module) |
运行/编译 | npm run dev (开发)或 npm run build (生产) |
通过以上步骤,初学者可以快速搭建支持 TypeScript + ES Module 的 Node.js 项目,享受静态类型检查和现代模块系统的便利! 🚀