要用 Cursor 搭建一个真正可部署上线的 Node.js 项目，需要完整覆盖代码编写、依赖管理、环境配置、API 接口开发、异常处理、日志记录、进程守护以及部署准备等关键环节：先初始化项目结构并将 src/index.js 设为入口文件，同时修改 package.json 中的 "main" 字段；再启用 ES 模块支持或配置 nodemon 实现热重载；使用原生 http 模块启动服务并监听环境变量端口，提供 /health 健康检查接口；接入 pino 结构化日志并统一捕获全局错误；编写 Dockerfile，通过 npm ci 构建生产镜像；最后在本地完成镜像构建并验证健康接口是否返回 200 以及正确的响应头。

使用Cursor开发一个可以正式上线的Node.js项目，必须打通从代码实现到部署交付的完整流程，涵盖代码编写、依赖管理、运行环境配置、API接口实现、错误处理、日志记录、进程守护和上线准备，不能只满足于“本地能运行”。

初始化项目结构

在Cursor中新建项目文件夹后，右键打开终端，执行 npm init -y，先生成基础的 package.json 文件。

随后手动创建 src/ 目录，并将项目入口文件明确设置为 src/index.js，不要直接把主程序写在根目录中——否则后续在 Docker 部署或 PM2 进程管理场景下，容易因为路径混乱而找不到启动文件。

接着编辑 package.json，把 "main" 字段修改为 "src/index.js"，【如果这里不修改，线上启动时很容易出现“Cannot find module”报错】。

配置ES模块与热重载

方法一：直接在 package.json 中加入 "type": "module"，开启 Node.js 原生 ES Module 支持。

方法二：安装 nodemon 并配置开发脚本："dev": "nodemon --watch src --ext js,jsx --exec node --no-warnings src/index.js"。这一步建议保留 --no-warnings，否则在 Node 20+ 环境下，ExperimentalWarning 可能频繁刷屏，影响本地调试体验。

执行 npm run dev 后，修改任意 .js 文件并保存，服务应自动重启，同时确认控制台输出 “Server running on http://localhost:3000”，以验证热更新配置生效。

实现基础HTTP服务

第一步：在 src/index.js 中通过原生 http 模块创建并启动服务，不额外引入 Express 等 Web 框架——这样可以减少线上依赖数量，同时降低安全扫描和维护成本。

第二步：监听 process.env.PORT || 3000，优先读取环境变量中的端口配置；如果本地未设置则默认使用 3000，但实际部署上线时必须依赖 PaaS 平台注入真实端口。

第三步：编写基础路由逻辑，当访问 GET /health 时返回 { "status": "ok", "timestamp": Date.now() }，并确保状态码为 200。这个健康检查接口通常会被云平台或容器编排系统调用，【如果返回非200或响应超时，实例可能会被自动摘除或下线】。

添加生产级日志与错误捕获

安装 pino：npm install pino，不要继续使用 console.log——因为它既不方便区分日志级别，也无法提供结构化日志输出，难以满足生产环境排障需求。

在 src/logger.js 中初始化日志实例：const logger = pino({ level: process.env.LOG_LEVEL || 'info' })，然后导出 logger 供全项目复用。

接下来在 src/index.js 顶部引入 logger，并把所有 console.* 调用统一替换掉。例如，请求日志可以写成：logger.info({ method, url, ip: req.socket.remoteAddress }, 'incoming request')。

还需要为服务器实例绑定 'error' 事件，在捕获异常后执行 logger.error(err)，再调用 process.exit(1) 主动退出，避免未捕获错误导致进程静默挂起，影响服务可用性。

编写Docker部署所需文件

在项目根目录创建 Dockerfile，内容如下：

这份 Dockerfile 设计得非常简洁，部署思路也足够清晰：首先使用 FROM node:20-alpine 作为基础镜像，尽量缩小运行环境体积；然后通过 WORKDIR /app 固定工作目录。接着优先执行 COPY package*.json ./，再配合 RUN npm ci --only=production 安装生产依赖，这样不仅安装过程更稳定，也更利于复用 Docker 镜像缓存。之后再通过 COPY src ./src 复制业务代码，使用 EXPOSE 3000 声明服务端口，并通过 ENV NODE_ENV=production 明确生产环境运行模式。最后在容器启动时，通过 CMD ["node", "src/index.js"] 直接启动 Node.js 应用，整体流程清晰高效，没有多余步骤。

关键点：一定要使用 npm ci，而不是 npm install，这样才能确保依赖版本与 package-lock.json 严格一致；同时使用 --only=production 排除开发依赖，从而减小最终镜像体积并提升部署效率。

准备上线前最后验证

在Cursor终端中执行：docker build -t my-node-app . && docker run -p 3000:3000 my-node-app。

然后访问 http://localhost:3000/health，确认接口能够正常返回 JSON，且 HTTP 状态码为 200。

再使用 curl -I http://localhost:3000/health 查看响应头，重点确认包含 Content-Type: application/json 和 Connection: keep-alive，以验证服务的基础响应配置正确无误。