প্রোডাকশনে 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 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: প্যাকেজটি dev-নির্ভরতার মধ্যে রয়েছে

প্রোডাকশন ইন্সটল করে ডেভেলপমেন্ট নির্ভরতা এড়িয়ে যায়, তাই রানটাইম কোড দ্বারা আমদানি করা যেকোনো কিছু অবশ্যই নিয়মিত নির্ভরতা হতে হবে।

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 একটি চিত্রের মধ্যে নেটিভ মডিউলগুলি ভেঙে যায়, কারণ ম্যাকওএস বা আপনার আর্কিটেকচারের জন্য সংকলিত বাইনারিগুলি কন্টেইনারের প্ল্যাটফর্মে লোড হবে না।

# .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: ESM-এ ফাইল এক্সটেনশন অনুপস্থিত

ES মডিউলগুলির আপেক্ষিক আমদানিতে এক্সটেনশন প্রয়োজন। CommonJS করে না। তাদের মধ্যে স্থানান্তর অবিলম্বে এটি পৃষ্ঠ.

ESM-তে কম্পাইল করা টাইপস্ক্রিপ্টে, আমদানি নির্দিষ্টকারীকে অবশ্যই

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

আউটপুট ফাইল, তাই আপনি লিখুন যদিও উৎস হল.jsকারণ 6: টাইপস্ক্রিপ্ট পাথ উপনাম রানটাইমে সমাধান করা হয়নি.ts.

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

উপনাম

একটি কম্পাইল সময় সুবিধা হয়. কম্পাইলার তাদের পুনঃলিখন করে না, তাই নির্গত জাভাস্ক্রিপ্টে এখনও রয়েছেtsconfig.json, যা নোড সমাধান করতে পারে না।@/utils/loggerহয় কম্পাইল করার পরে পাথগুলি পুনরায় লিখুন, অথবা একটি রানটাইম সমাধানকারী নিবন্ধন করুন।

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

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

esbuild, tsup, বা অনুরূপ সাথে Bundling এছাড়াও বিল্ডের সময় উপনামগুলি সমাধান করে, যে কারণে বান্ডিল স্থাপনা খুব কমই এটিকে আঘাত করে।

npm install -D tsc-alias

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

কারণ 7: বিল্ড আউটপুট স্থাপন করা হয়নি

জন্য প্রবেশ

A .gitignore or .dockerignore সঠিক – কিন্তু তারপর বিল্ডটি অবশ্যই সার্ভারে বা CI তে চালাতে হবে। আসলে কি পাঠানো হয়েছে তা নিশ্চিত করুন।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প্রতিরোধ

লিনাক্সে CI চালান যাতে কেস-সংবেদনশীলতার সমস্যাগুলি মার্জ করার আগে ব্যর্থ হয়

• সাথে পরীক্ষা
• ভুল স্থানান্তরিত নির্ভরতা ধরতে সিআই-তেnpm ci --omit=devসর্বদা
• তোমার.dockerignoreলকফাইলটি কমিট করুন এবং ব্যবহার করুনnode_modules
• , কখনই নাnpm ci, নির্মাণেnpm installডকারফাইলে এবং
• এ নোড প্রধান সংস্করণটি পিন করুন বিশুদ্ধ-জাভাস্ক্রিপ্ট প্যাকেজ পছন্দ করুন যেখানে একটি নেটিভ মডিউল প্রয়োজন নেইengines
• প্রায়শই জিজ্ঞাসিত প্রশ্ন

প্রশ্নঃ কেন এটি স্থানীয়ভাবে কাজ করে কিন্তু ডকারে নয়?

উত্তর: বিভিন্ন ফাইল সিস্টেম কেস সংবেদনশীলতা, নেটিভ বাইনারিগুলির জন্য আলাদা প্ল্যাটফর্ম, এবং যদি আপনি স্থানীয়ভাবে dev নির্ভরতাগুলির সাথে ইনস্টল করেন তবে একটি ভিন্ন নির্ভরতা সেট৷ তিনটি ইমেজ ভিতরে ইনস্টল করে নির্মূল করা হয়.
প্রশ্ন: আমার কি node_modules কমিট করা উচিত?

উত্তর: না। লকফাইলটি কমিট করুন এবং বিল্ডের সময় ইন্সটল করুন। প্রতিশ্রুতিবদ্ধ নির্ভরতা প্ল্যাটফর্ম পরিবর্তনের উপর ভেঙে যায় এবং ভান্ডারকে খারাপভাবে ফুলে যায়।
প্রশ্ন: npm ci বা npm উৎপাদনে ইনস্টল?

. ম্যানিফেস্ট এবং লকফাইল একমত না হলে এটি লকফাইলটি ঠিক যা নির্দিষ্ট করে এবং ব্যর্থ হয় তা ইনস্টল করে, যা আপনি একটি বিল্ডে চান৷
A: npm ciপ্রশ্ন: আমি কিভাবে একটি বড় কোডবেস জুড়ে কেস অমিল খুঁজে পাব?

উত্তর: সিআই-তে লিনাক্সে তৈরি করুন। এটি একমাত্র নির্ভরযোগ্য পদ্ধতি – একটি কেস-অসংবেদনশীল ফাইল সিস্টেমের স্থানীয় টুলিং সমস্যাটি দেখতে পারে না।
প্রশ্ন: মডিউলটি node_modules এ রয়েছে কিন্তু এখনও পাওয়া যায়নি। কেন?

উত্তর: সাধারণত একটি নেস্টেড নির্ভরতা দ্বন্দ্ব, একটি ওয়ার্কস্পেস সেটআপ থেকে একটি ভাঙা সিমলিঙ্ক, বা একটি প্যাকেজ যার
ক্ষেত্রটি আপনি যে সাবপথটি আমদানি করছেন তা প্রকাশ করে না। প্যাকেজ চেক করুনexports এর মধ্যে মানচিত্রexportsউপসংহারpackage.json.

শুধুমাত্র উৎপাদন

শুধুমাত্র উৎপাদনMODULE_NOT_FOUNDত্রুটিগুলি পরিবেশগত পার্থক্য থেকে আসে। তাদের ক্রমানুসারে পরীক্ষা করুন:লিনাক্সের বিরুদ্ধে কেস সংবেদনশীলতা, devDependencies এ বসে রানটাইম আমদানি, ছবিতে কপি করা একটি স্থানীয়ভাবে নির্মিত নোড_মডিউল, ভুল প্ল্যাটফর্মের জন্য সংকলিত নেটিভ মডিউল, অনুপস্থিত.js ESM এর অধীনে এক্সটেনশন, এবং অমীমাংসিত TypeScript পাথ উপনাম। তাদের প্রায় সকলের জন্য কাঠামোগত সমাধান একই — লক্ষ্য পরিবেশের মধ্যে তৈরি এবং ইনস্টল করুন, লিনাক্সে CI চালান এবং ব্যবহার করুনnpm ci একটি প্রতিশ্রুতিবদ্ধ লকফাইল সহ।