Render部署Fastify+TypeScript服务报错：找不到typescript模块

问题背景 #

部署基于Fastify和TypeScript构建的后端服务时，执行构建脚本持续报错「Cannot find module 'typescript'」，即使将typescript在dependencies和devDependencies之间切换也无法解决。报错栈信息如下：

Error: Cannot find module 'typescript'
Nov 27 02:46:49 AM Require Module._extensions..js (node:internal/modules/cjs/loader:1435:10)
Nov 27 02:46:49 AM at Module.load (node:internal/modules/cjs/loader:1207:32)
Nov 27 02:46:49 AM at Module._load (node:internal/modules/cjs/loader:1023:12)
Nov 27 02:46:49 AM at Module.require (node:internal/modules/cjs/loader:1235:19)
Nov 27 02:46:49 AM ==> Build failed 😞

当前package.json配置：

{
    "name": "expense-manager-back",
    "version": "1.0.0",
    "description": "Expense Manager.",
    "main": "index.js",
    "scripts": {
        "dev": "tsx watch src/server.ts",
        "build": "npm install && npx tsup src --out-dir build",
        "start": "node build/server.js",
        "test": "vitest run",
        "test:watch": "vitest"
    },
    "keywords": [],
    "author": "",
    "license": "ISC",
    "devDependencies": {
        "@rocketseat/eslint-config": "2.1.0",
        "@types/bcryptjs": "2.4.6",
        "@types/node": "20.9.0",
        "@typescript-eslint/eslint-plugin": "6.10.0",
        "@typescript-eslint/parser": "6.10.0",
        "eslint": "8.53.0",
        "prisma": "5.5.2",
        "tsup": "7.2.0",
        "tsx": "4.0.0",
        "vite-tsconfig-paths": "4.2.1",
        "vitest": "0.34.6"
    },
    "dependencies": {
        "typescript": "5.2.2",
        "@fastify/cors": "8.0.0",
        "@fastify/jwt": "7.2.3",
        "@prisma/client": "5.5.2",
        "bcryptjs": "2.4.3",
        "dotenv": "16.3.1",
        "fastify": "4.24.3",
        "zod": "3.22.4"
    }
}

核心原因分析 #

报错本质是构建阶段的tsup（TypeScript打包工具）无法找到typescript依赖，常见触发场景：

1. 部署平台默认以生产模式执行npm install（如npm install --production或npm ci --only=production），跳过了devDependencies中的tsup，导致npx tsup临时下载依赖时出现版本匹配或网络问题。
2. 项目缺少明确的tsconfig.json配置，tsup无法自动定位TypeScript编译规则，间接引发依赖查找失败。
3. 缓存残留导致依赖安装不完整。

解决方案 #

方案1：调整构建脚本，确保安装所有依赖 #

修改package.json中的build脚本，强制安装包括devDependencies在内的所有依赖，并直接调用本地tsup而非npx：

"scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "npm install --include=dev && tsup src --out-dir build",
    "start": "node build/server.js",
    "test": "vitest run",
    "test:watch": "vitest"
}

如果部署平台支持自定义构建命令，直接设置为npm run build即可，无需额外参数。

方案2：添加tsup配置文件与tsconfig.json #

1. 在项目根目录创建tsup.config.ts，明确指定编译入口、输出目录及TypeScript配置路径：

import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/server.ts'],
  outDir: 'build',
  platform: 'node',
  target: 'node20', // 与你使用的Node版本匹配
  tsconfig: './tsconfig.json',
  clean: true, // 构建前清理输出目录
})

2. 补充tsconfig.json文件（根据项目需求调整）：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

方案3：清理依赖缓存后重新构建 #

在部署环境执行以下命令，彻底清理缓存并重新安装依赖：

rm -rf node_modules package-lock.json
npm install
npm run build

方案4：检查部署平台的构建配置 #

多数PaaS平台（如Render、Vercel）允许自定义构建命令和环境变量：

• 确保构建命令未添加--production参数；
• 若平台默认使用npm ci，改为npm ci（不带--only=production），确保安装所有依赖。

内容的提问来源于stack exchange，提问作者Ícaro Cedraz