tsc build succeeds but node dist/index.js throws ERR_MODULE_NOT_FOUND on extensionless import

发生场景

Moving the huobao-drama backend from npx tsx src/index.ts to a compiled production start (npm run build then node dist/index.js) inside a systemd unit. The build completed with no errors; the service crashed on startup.

问题

npm run build exited 0, but node dist/index.js crashed immediately with ERR_MODULE_NOT_FOUND pointing at dist/services/adapters/registry. The TypeScript source imported it extensionless (from './registry'); tsx resolves that fine, but Node's native ESM loader refuses. The build was 'successful' yet produced output that cannot run under plain node.

报错原文（已脱敏/规范化）

code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/<user>/workspace/huobao-drama/backend/dist/services/adapters/registry'
Node.js v24.20.0
(npm run build had exited 0 just before)

适用环境

Node 24, TypeScript (tsc build), tsx runner, Linux. Backend source uses ESM-style imports.

如何确认是这个问题

Run the built output directly: node dist/index.js → expect: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../dist/services/adapters/registry'. Then check the source import: grep -rn "from ['\"]\./registry['\"]" src/ → expect: an extensionless relative import (no .js). If the import already has an extension, it is not this problem.

不是这个问题时 / 边界

If the missing module is a third-party package (not a relative ./ path), that is a node_modules/install problem, not this. If the error names a file WITH an extension, the file is genuinely absent — different cause.

根因

tsc compiles TypeScript but does not rewrite import paths. Node's native ESM loader requires explicit file extensions on relative imports; tsx's resolver is lenient and resolves extensionless paths. So code that runs fine under tsx crashes under plain node, even though the build itself reported success.

修复步骤

1. Confirm it is this problem: node dist/index.js → expect: Error [ERR_MODULE_NOT_FOUND] naming a relative path without extension
2. Find all extensionless relative imports: grep -rn "from ['\"]\.\./" src/ | grep -v "\.js['\"]" → expect: the offending lines
3. Fix option A (proper): add explicit .js extensions to the relative imports in src/, rebuild → expect: node dist/index.js starts
4. Fix option B (pragmatic): keep sources as-is and run with tsx (tsx src/index.ts) instead of node on dist → expect: service starts, /api/v1/dramas → 200
5. Verify the service answers: curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:5679/api/v1/dramas → expect: 200

如何验证

The process stays up under the chosen runner and the health endpoint returns 200; no ERR_MODULE_NOT_FOUND in the log on restart.

试过没用的办法

Rebuilding did not help — tsc kept emitting the same unrunnable output because the source itself was the problem. Downgrading Node did not help either; this is spec behavior of the ESM loader, not a version bug.

如何回滚

Revert the import edits, or point the systemd unit / start script back at tsx.

风险提示

Low. If you add .js extensions, make sure tsx/ts-node still resolve them (they do). Switching the runner back to tsx keeps a dev-style dependency in production.

验证范围

Node 18+ ESM, TypeScript, tsx; Oct 2026

何时失效

When the codebase adopts explicit .js extensions on all relative imports, or switches moduleResolution to bundler/nodenext consistently with a path-rewriting build.