وحدة path في Node.js: path.join مقابل path.resolve

تضم path.join() مقاطع المسار بالفاصل الصحيح وتنظف .. والشرطات المائلة المكررة، لكنها تُبقي النتيجة نسبية إذا بدأت بمقطع نسبي. أما path.resolve() فتقوم بالعمل نفسه بدءًا من المقطع الأخير رجوعًا إلى الأول، وتعيد دائمًا مسارًا مطلقًا: تنطلق من مجلد العمل الحالي، وأي مقطع مطلق في الطريق يبدأ المسار من جديد. استخدم join لبناء مسار، وresolve حين تحتاج مسارًا مطلقًا.

const path = require('path');

console.log(path.join('users', 'ada', 'notes.txt'));
console.log(path.join('users', 'ada', '..', 'grace', 'todo.txt'));
console.log(path.join('/srv/app/', '/public/', 'index.html'));
console.log(path.join('src', '', 'lib//utils.js'));

طبع users/ada/notes.txt، ثم users/grace/todo.txt (أزال .. المقطع ada)، ثم /srv/app/public/index.html وsrc/lib/utils.js: اختفت الشرطات الزائدة والمقاطع الفارغة. لا تعامل join المقطع /public/ أبدًا كبداية جديدة؛ هو مجرد المقطع التالي.

path.join مقابل path.resolve

يظهر الفرق حين يبدأ مقطع بـ / أو حين يكون المقطع الأول نسبيًا:

const path = require('path');

console.log('join:   ', path.join('/srv/app', '/public', 'img'));
console.log('resolve:', path.resolve('/srv/app', '/public', 'img'));

console.log('join:   ', path.join('/srv/app', '../logs'));
console.log('resolve:', path.resolve('/srv/app', '../logs'));

const rel = path.join('public', 'index.html');
const abs = path.resolve('public', 'index.html');
console.log(rel, path.isAbsolute(rel));
console.log(path.isAbsolute(abs), path.relative(process.cwd(), abs));

مع وجود /public في الوسط، أنتجت join المسار /srv/app/public/img بينما تخلّصت resolve من كل ما سبقه وأنتجت /public/img؛ وتعامل الاثنان مع .. بالطريقة نفسها. يبيّن السطران الأخيران أن join أبقت public/index.html نسبيًا، بينما جعلته resolve مطلقًا بإضافة المجلد الحالي في بدايته.

basename وdirname وextname وparse

هذه الدوال تفكك المسار. تنظر إلى النص فقط: لا يلزم أن يكون الملف موجودًا.

const path = require('path');

const file = '/home/ada/photos/cat.final.jpg';

console.log(path.basename(file));
console.log(path.basename(file, '.jpg'));
console.log(path.dirname(file));
console.log(path.extname(file));
console.log(JSON.stringify(path.parse(file)));

طبع cat.final.jpg وcat.final و/home/ada/photos و.jpg: تأخذ extname الجزء الواقع بعد آخر نقطة فقط. تعيد path.parse كل ذلك دفعة واحدة (root وdir وbase وext وname)، وتحوّل path.format كائنًا كهذا إلى نص من جديد.

__dirname و__filename

في ملف CommonJS، __dirname هو المسار المطلق للمجلد الذي يحتوي الملف، و__filename هو الملف نفسه. المسار النسبي مثل 'data.json' يُحسب نسبةً إلى المكان الذي شغّل منه المستخدم node، وهذا ينكسر بمجرد أن يشغّل أحدهم سكربتك من مجلد آخر. ابنِ المسارات من __dirname بدلًا من ذلك:

const fs = require('fs');
const path = require('path');

const configPath = path.join(__dirname, 'config.json');

fs.writeFileSync(configPath, '{ "theme": "dark" }'); // setup
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));

console.log(path.basename(configPath), config.theme);
console.log(path.relative(__dirname, __filename));

طبع config.json dark وindex.js. تختلف المسارات الكاملة من جهاز لآخر، ولهذا بالضبط تبنيها بـ path.join(__dirname, ...) بدلًا من كتابتها يدويًا.

__dirname في ES modules: import.meta.dirname

لا يوجد __dirname في ES modules؛ واستخدامه يرمي ReferenceError: __dirname is not defined in ES module scope. منذ Node.js 20.11 حلّ محلهما import.meta.dirname وimport.meta.filename:

import path from 'node:path';

const dataFile = path.join(import.meta.dirname, 'data', 'users.json');

console.log(path.basename(import.meta.filename));
console.log(path.relative(import.meta.dirname, dataFile));

طبع index.js وdata/users.json. في نسخ Node.js الأقدم من 20.11، استخرج المجلد من عنوان URL الخاص بالوحدة: path.dirname(fileURLToPath(import.meta.url))، مع fileURLToPath من node:url.

لماذا لا تضم المسارات بالنصوص

'data' + '/' + file يعمل على macOS وLinux، ثم يفشل على Windows حيث الفاصل هو \، ولا يفعل شيئًا حيال .. أو الشرطات المكررة أو الشرطة الناقصة. تستخدم path قواعد النظام الذي تعمل عليه. ويمكنك رؤية نتيجة Windows من أي جهاز عبر path.win32:

const path = require('path');

path.posix.join('users', 'ada', 'notes.txt'); // 'users/ada/notes.txt'
path.win32.join('users', 'ada', 'notes.txt'); // 'users\\ada\\notes.txt'
path.sep;                                     // '/' on macOS and Linux, '\\' on Windows

مرّر نتيجة path.join إلى fs.readFile وستقرأ الشيفرة نفسها الملف على كل نظام.

أخطاء شائعة

توقّع أن extname تعرف الامتدادات المزدوجة. path.extname('archive.tar.gz') هي '.gz'، والملف الذي يبدأ بنقطة مثل .env لا امتداد له أصلًا: path.extname('.env') هي ''. افحص نهاية الاسم بنفسك حين تهمك اللاحقة كاملة.

الوثوق بأن join تُبقي المستخدم داخل مجلد. path.join('/srv/app', '../../etc/passwd') هي '/etc/passwd'. قبل أن تقرأ ملفًا يحدد اسمه طلبٌ ما، حلّ المسار وتحقق من أنه ما زال يبدأ بمجلدك.