उत्पादन में Node.js को तैनात करने के बाद MODULE_NOT_FOUND त्रुटि को कैसे ठीक करें

Error: Cannot find module './Utils/logger'यह आपकी मशीन पर पूरी तरह से काम करता है और तैनात होते ही विफल हो जाता है। बग के इस वर्ग के बहुत कम कारण हैं, और उनमें से लगभग सभी आपके विकास परिवेश और सर्वर के बीच अंतर पैदा करते हैं।

कारण 1: केस संवेदनशीलता (सबसे आम)

macOS और Windows डिफ़ॉल्ट रूप से केस-असंवेदनशील फ़ाइल सिस्टम का उपयोग करते हैं। लिनक्स नहीं करता. तोrequire('./Utils/logger') resolves a file named utils/logger.jsनामक फ़ाइल का समाधान करता है आपके लैपटॉप पर और सर्वर पर विफल रहता है।

// File on disk: src/utils/logger.js

const logger = require('./Utils/logger');   // works on macOS, fails on Linux
const logger = require('./utils/logger');   // ✅ correct everywhere

Git ने वास्तव में क्या रिकॉर्ड किया है, इसकी जांच करके तैनाती से पहले इन्हें ढूंढें, जो आपके स्थानीय फ़ाइल सिस्टम की परवाह किए बिना आधिकारिक है।

# List tracked paths and eyeball the casing
git ls-files | grep -i utils

# Catch a rename that Git ignored because only the case changed
git config core.ignorecase false
git status

यदि Git ने गलत मामला दर्ज किया है, तो एक मध्यवर्ती नाम के माध्यम से नाम बदलने के लिए बाध्य करें।

git mv src/Utils src/utils-tmp
git mv src/utils-tmp src/utils
git commit -m "fix: correct directory casing for case-sensitive filesystems"

विश्वसनीय रोकथाम एक सीआई कार्य है जो लिनक्स पर चलता है। यह तैनाती के बजाय प्रत्येक पुल अनुरोध पर इसे पकड़ता है।

कारण 2: पैकेज निर्भरता में है

उत्पादन इंस्टॉल विकास निर्भरता को छोड़ देता है, इसलिए रनटाइम कोड द्वारा आयात की गई कोई भी चीज़ नियमित निर्भरता होनी चाहिए।

npm ci --omit=dev        # devDependencies are not installed

{
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "dotenv": "^17.0.0"     // ❌ but required at runtime in server.js
  }
}

# Move it
npm uninstall dotenv
npm install dotenv

प्रत्येक मामले को एक साथ ढूंढने के लिए, उत्पादन निर्भरता को एक साफ़ निर्देशिका में स्थापित करें और एप्लिकेशन प्रारंभ करें।

rm -rf node_modules
npm ci --omit=dev
node dist/server.js

कारण 3: नोड_मॉड्यूल को डॉकर में कॉपी किया गया

स्थानीय रूप से निर्मितnode_modulesकी प्रतिलिपि बनाना एक छवि में मूल मॉड्यूल टूट जाता है, क्योंकि macOS या आपके आर्किटेक्चर के लिए संकलित बायनेरिज़ कंटेनर के प्लेटफ़ॉर्म पर लोड नहीं होंगे।

# .dockerignore — essential
node_modules
npm-debug.log
.git
dist
.env

# Dockerfile — install inside the image
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

नकल करनाpackage*.json शेष स्रोत से पहले एक जानबूझकर परत-कैशिंग विकल्प है: निर्भरताएँ केवल तभी पुनः स्थापित की जाती हैं जब प्रकट परिवर्तन होता है, प्रत्येक स्रोत संपादन पर नहीं।

कारण 4: गलत प्लेटफ़ॉर्म के लिए निर्मित मूल मॉड्यूल

संकलित घटकों के साथ पैकेज –bcrypt, sharp, canvas, डेटाबेस ड्राइवर – प्लेटफ़ॉर्म-विशिष्ट बायनेरिज़ का उत्पादन करते हैं।

Error: Cannot find module '.../node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node'

उन्हें लक्ष्य प्लेटफ़ॉर्म पर पुनर्निर्माण करें, या ऊपर बताए अनुसार कंटेनर के अंदर स्थापित करें।

npm rebuild bcrypt --build-from-source

# Alpine images need build tools for native compilation
RUN apk add --no-cache python3 make g++

जहां एक शुद्ध-जावास्क्रिप्ट विकल्प मौजूद है –bcryptjs इसके बजायbcrypt, उदाहरण के लिए – इसका उपयोग करने से परिनियोजन समस्या की यह संपूर्ण श्रेणी दूर हो जाती है।

कारण 5: ईएसएम में गुम फ़ाइल एक्सटेंशन

ईएस मॉड्यूल को सापेक्ष आयात में विस्तार की आवश्यकता होती है। कॉमनजेएस नहीं करता है। उनके बीच प्रवासन से यह तुरंत सामने आता है।

// package.json has "type": "module"
import { logger } from './utils/logger';        // ❌ ERR_MODULE_NOT_FOUND
import { logger } from './utils/logger.js';     // ✅

ईएसएम के लिए संकलित टाइपस्क्रिप्ट में, आयात विनिर्देशक कोका संदर्भ देना चाहिए आउटपुट फ़ाइल, तो आप लिखें.js भले ही स्रोत.ts.

import { logger } from './utils/logger.js';   // correct — refers to compiled output

है कारण 6: टाइपस्क्रिप्ट पथ उपनाम रनटाइम पर हल नहीं हुए

उपनामtsconfig.jsonमें एक संकलन-समय सुविधा है। कंपाइलर उन्हें दोबारा नहीं लिखता है, इसलिए उत्सर्जित जावास्क्रिप्ट में अभी भी@/utils/loggerशामिल है , जिसे नोड हल नहीं कर सकता।

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

// Compiles fine, fails at runtime:
// Error: Cannot find module '@/utils/logger'
import { logger } from '@/utils/logger';

या तो संकलन के बाद पथों को फिर से लिखें, या रनटाइम रिज़ॉल्वर पंजीकृत करें।

npm install -D tsc-alias

# package.json
"build": "tsc && tsc-alias"

esbuild, tsup, या इसी तरह के साथ बंडलिंग भी निर्माण के दौरान उपनामों को हल करता है, यही कारण है कि बंडल की तैनाती शायद ही कभी इस पर असर डालती है।

कारण 7: बिल्ड आउटपुट तैनात नहीं किया गया था

A .gitignore or .dockerignore entry for distके लिए प्रविष्टि सही है – लेकिन तब बिल्ड को सर्वर पर या सीआई में चलना चाहिए। पुष्टि करें कि वास्तव में क्या भेजा गया है।

# Inspect the running container
docker exec -it <container> ls -la /app/dist
docker exec -it <container> ls -la /app/node_modules | head

व्यवस्थित रूप से निदान

# 1. Which exact path is Node looking for?
node dist/server.js
# Read the full error — it prints the resolved path it tried.

# 2. Does that path exist on the server?
ls -la /app/dist/utils/

# 3. Is the package installed?
ls /app/node_modules | grep package-name
npm ls package-name

# 4. Trace resolution in detail
NODE_DEBUG=module node dist/server.js 2>&1 | head -50

# 5. Confirm the Node version matches your local one
node --version

NODE_DEBUG=module प्रत्येक निर्देशिका नोड जाँच को प्रिंट करता है, जो आमतौर पर समस्या को कुछ पंक्तियों में स्पष्ट कर देता है।

रोकथाम

• Linux पर CI चलाएँ ताकि मर्ज से पहले केस-संवेदनशीलता समस्याएँ विफल हो जाएँ
• के साथ परीक्षण करें गलत निर्भरता को पकड़ने के लिए सीआई मेंnpm ci --omit=devहमेशा
• आपका.dockerignoreलॉकफ़ाइल प्रतिबद्ध करें औरnode_modules
• का उपयोग करें , कभी नहींnpm ci, बिल्ड्स मेंnpm installDockerfile और
• में नोड प्रमुख संस्करण को पिन करें शुद्ध-जावास्क्रिप्ट पैकेज को प्राथमिकता दें जहां मूल मॉड्यूल आवश्यक नहीं हैengines
• अक्सर पूछे जाने वाले प्रश्न

प्रश्न: यह स्थानीय स्तर पर क्यों काम करता है लेकिन डॉकर में नहीं?

ए: यदि आप स्थानीय रूप से देव निर्भरता के साथ इंस्टॉल करते हैं तो अलग फ़ाइल सिस्टम केस संवेदनशीलता, मूल बायनेरिज़ के लिए अलग प्लेटफ़ॉर्म और एक अलग निर्भरता सेट। छवि के अंदर स्थापित करके तीनों को हटा दिया जाता है।
प्रश्न: क्या मुझे नोड_मॉड्यूल प्रतिबद्ध करना चाहिए?

उ: नहीं। निर्माण के दौरान लॉकफ़ाइल प्रतिबद्ध करें और इंस्टॉल करें। प्लेटफ़ॉर्म परिवर्तन पर प्रतिबद्ध निर्भरताएँ टूट जाती हैं और रिपॉजिटरी बुरी तरह से ख़राब हो जाती है।
प्रश्न: एनपीएम सीआई या एनपीएम उत्पादन में स्थापित करें?

. यह बिल्कुल वही इंस्टॉल करता है जो लॉकफ़ाइल निर्दिष्ट करता है और यदि मेनिफेस्ट और लॉकफ़ाइल असहमत होते हैं तो विफल हो जाता है, जो कि आप बिल्ड में चाहते हैं।
A: npm ciप्रश्न: मैं बड़े कोडबेस में केस बेमेल कैसे ढूंढूं?

उ: सीआई में लिनक्स पर निर्माण करें। यह एकमात्र विश्वसनीय तरीका है – केस-असंवेदनशील फ़ाइल सिस्टम पर स्थानीय टूलिंग समस्या को नहीं देख सकती है।
प्रश्न: मॉड्यूल नोड_मॉड्यूल में है लेकिन अभी भी नहीं मिला है। क्यों?

ए: आमतौर पर एक नेस्टेड निर्भरता संघर्ष, कार्यक्षेत्र सेटअप से एक टूटा हुआ सिम्लिंक, या एक पैकेज जिसका
फ़ील्ड आपके द्वारा आयात किए जा रहे उपपथ को उजागर नहीं करता है। पैकेज की जाँच करेंexports इसके मानचित्र मेंexportsनिष्कर्षpackage.json.

केवल उत्पादन

केवल उत्पादनMODULE_NOT_FOUNDत्रुटियाँ पर्यावरण के अंतर से आती हैं। उन्हें क्रम से जांचें:लिनक्स के विरुद्ध केस संवेदनशीलता, देवनिर्भरता में बैठे रनटाइम आयात, छवि में कॉपी किए गए स्थानीय रूप से निर्मित नोड_मॉड्यूल, गलत प्लेटफ़ॉर्म के लिए संकलित मूल मॉड्यूल, गायब.js ईएसएम के अंतर्गत एक्सटेंशन, और अनसुलझे टाइपस्क्रिप्ट पथ उपनाम। उनमें से लगभग सभी के लिए संरचनात्मक निर्धारण समान है – लक्ष्य वातावरण के अंदर निर्माण और स्थापित करें, लिनक्स पर सीआई चलाएं, औरnpm ciका उपयोग करें एक प्रतिबद्ध लॉकफ़ाइल के साथ।