Next.js项目中如何运行导入项目源码的独立TypeScript脚本

直接用node执行脚本出现导入错误的核心原因是：Node原生不支持TypeScript语法转译，同时无法识别Next.js项目里配置的路径别名、模块解析规则、环境变量加载逻辑，以下是经过社区验证的可落地方案，按推荐优先级排序：

方案1：Next.js 原生指令运行（v13.4+ 适用，零额外依赖） #

Next.js 13.4及以上版本内置了独立脚本运行能力，会自动复用项目的所有编译配置、路径别名、环境变量规则，不需要安装任何第三方依赖。
操作步骤：

• 将脚本放在项目任意目录，推荐统一放在scripts/文件夹下，例如scripts/db-query.ts
• 如果脚本中导入了Next.js服务端模块（如数据库连接实例、服务端工具函数），在文件顶部添加运行时声明：

export const runtime = 'nodejs'

• 根目录执行命令即可运行：

# 开发环境运行
npx next dev scripts/db-query.ts
# 生产环境运行，执行速度更快
npx next build && npx next start scripts/db-query.ts

该方案会自动加载项目内所有优先级的环境变量文件，不需要额外配置dotenv

方案2：tsx 运行（全版本兼容，社区通用方案） #

如果使用的是低于13.4的Next.js版本，优先选择tsx作为运行时，它内置了极速TS转译、ESM/CJS自动适配、tsconfig路径别名解析能力，和Next.js的依赖链几乎没有冲突。
操作步骤：

• 安装开发依赖：

npm install -D tsx
# 若需要自动加载Next.js环境变量，同时安装dotenv
npm install -D dotenv

• 如果需要读取.env.local/.env中的环境变量，在脚本最顶部添加导入语句：

import 'dotenv/config'
// 后续正常导入项目内的模块、写业务逻辑即可
import { db } from '@/lib/db'

• 执行命令运行脚本：

npx tsx scripts/db-query.ts
# 传参直接追加在命令后，例如 npx tsx scripts/db-query.ts --userId=1001

注意：tsx 不会自动加载 Next.js 规则下的环境变量文件，必须手动引入dotenv或者在执行命令时注入环境变量，否则读取process.env会得到undefined

常见问题规避 #

• 不推荐使用ts-node运行：ts-node的ESM解析逻辑和Next.js（尤其是App Router版本）的模块规则冲突概率极高，大概率会出现莫名的导入报错
• 脚本中尽量不要导入标记'use client'的客户端模块，这类模块依赖浏览器API，在Node环境下运行会触发window、document未定义的错误
• 高频运行的脚本可以在package.json中配置快捷命令：

{
  "scripts": {
    "db:query": "tsx scripts/db-query.ts"
  }
}

后续直接执行npm run db:query即可。

内容的提问来源于stack exchange，提问作者Alex Flint