Node.js package.json 配置详解 + TypeScript + ES Module 集成指南

以下是针对初学者的 ​​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. ​​依赖管理(dependenciesdevDependencies)​

​字段​ ​作用​ ​示例​
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):

    sql 复制代码
    npm install @types/lodash --save-dev

2. 报错:"TS2307: Cannot find module './utils' or its corresponding type declarations"

  • ​原因​ ​:TS 未正确识别自定义模块的路径(如 src/utils.ts)。

  • ​解决​​:

    • 确保 tsconfig.jsonrootDirinclude 配置正确(如 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.jsonmodule 字段,确保为 ESNextNodeNext

五、总结:关键步骤速查表

​步骤​ ​操作​
初始化项目 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 支持 devbuild 等命令
编写代码 使用 import/export 语法(ES Module)
运行/编译 npm run dev(开发)或 npm run build(生产)

通过以上步骤,初学者可以快速搭建支持 TypeScript + ES Module 的 Node.js 项目,享受静态类型检查和现代模块系统的便利! 🚀

相关推荐
江湖人称小鱼哥1 小时前
react接口防抖处理
前端·javascript·react.js
GISer_Jing1 小时前
腾讯前端面试模拟详解
前端·javascript·面试
萌萌哒草头将军2 小时前
🚀🚀🚀 Webpack 项目也可以引入大模型问答了!感谢 Rsdoctor 1.2 !
前端·javascript·webpack
小白的代码日记2 小时前
Springboot-vue 地图展现
前端·javascript·vue.js
teeeeeeemo2 小时前
js 实现 ajax 并发请求
开发语言·前端·javascript·笔记·ajax
清秋2 小时前
全网最全 ECMAScript 攻略( 更新至 ES2025)
前端·javascript·ecmascript 6
李明卫杭州3 小时前
深入理解CSS变量(Custom Properties)
前端·javascript
一枚前端小能手3 小时前
💫 回调套回调写到崩溃,异步编程其实可以很优雅
前端·javascript
用户47949283569154 小时前
深入理解JavaScript:手写实现Array.prototype.push方法
前端·javascript