url.fileURLToPath / pathToFileURL în Node.js

import { fileURLToPath, pathToFileURL } from "node:url";
fileURLToPath(urlFisier)
pathToFileURL(cale)

Ce face url.fileURLToPath / pathToFileURL

În modulele ES, Node.js identifică fișierele prin URL-uri file://: import.meta.url arată ca file:///home/ana/proiect/app.mjs. Funcțiile din node:fs acceptă direct un obiect URL, dar multe alte unelte cer o cale obișnuită.

fileURLToPath face conversia corectă: decodează caracterele codificate (%20 devine spațiu, %C4%83 devine „ă”) și, pe Windows, produce C:\.... pathToFileURL face invers și codifică singur caracterele speciale. Nu tăia prefixul file:// de mână.

Pentru directorul și calea scriptului curent, Node.js 20.11+ oferă direct import.meta.dirname și import.meta.filename. Despre clasa URL în general vezi pagina URL din secțiunea JavaScript.

Parametri

Parametru	Descriere
urlFisier	Pentru fileURLToPath: un URL sau un șir care începe cu file:.
cale	Pentru pathToFileURL: o cale; dacă este relativă, este rezolvată față de directorul curent.
opțiuni	{ windows: true } (Node.js 22.1+): conversie după regulile Windows, indiferent de sistem.

Ce returnează

fileURLToPath: un șir (calea). pathToFileURL: un obiect URL.

Exemple

Exemplul 1: Conversii în ambele sensuri

import { fileURLToPath, pathToFileURL } from "node:url";

const url = pathToFileURL("/home/ana/note de curs/anul 1.txt");
console.log(url.href);

console.log(fileURLToPath("file:///home/ana/documente/factur%C4%83.pdf"));
console.log(fileURLToPath("file:///C:/Users/Ana/cv.docx", { windows: true }));

Rezultat

file:///home/ana/note%20de%20curs/anul%201.txt
/home/ana/documente/factură.pdf
C:\Users\Ana\cv.docx

Exemplul 2: Fișier de lângă script prin import.meta.url

new URL("./date.json", import.meta.url) găsește fișierul relativ la script, nu la directorul curent. Exemplul afișează doar partea relativă a căii.

import { writeFile, readFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import path from "node:path";

const urlDate = new URL("./date.json", import.meta.url);
await writeFile(urlDate, JSON.stringify({ oras: "Iași" }));

console.log(urlDate.protocol);
console.log(path.relative(process.cwd(), fileURLToPath(urlDate)));
console.log(JSON.parse(await readFile(urlDate, "utf8")));

Rezultat

file:
date.json
{ oras: 'Iași' }

Exemplul 3: Calea scriptului: fileURLToPath sau import.meta.filename

import { fileURLToPath } from "node:url";
import path from "node:path";

const fisier = fileURLToPath(import.meta.url);
console.log(path.basename(fisier));
console.log(fisier === import.meta.filename);
console.log(path.dirname(fisier) === import.meta.dirname);

Rezultat

exemplu.mjs
true
true

Greșeli frecvente

• Folosești new URL(import.meta.url).pathname drept cale: rămân caracterele codificate (%20), iar pe Windows rezultatul arată ca /C:/Users/.... Folosește fileURLToPath.
• Construiești URL-ul cu "file://" + cale: spațiile și diacriticele nu sunt codificate. Folosește pathToFileURL.
• Folosești __dirname într-un modul ES și primești ReferenceError. Acolo există import.meta.dirname sau path.dirname(fileURLToPath(import.meta.url)).

Comenzi înrudite

• import.meta.dirname / filename: Calea directorului și a fișierului modulului curent: înlocuitorii pentru __dirname și __filename în module ES.
• path.join: Lipește mai multe bucăți într-o singură cale, cu separatorul corect pentru sistemul de operare, și curăță ./ și ../.
• Module ES (import) și CommonJS (require): Cele două sisteme de module din Node.js: import/export (ES) și require/module.exports (CommonJS), și cum le combini.
• fs.readFile: Citește tot conținutul unui fișier: ca text dacă dai codificarea („utf8”), altfel ca Buffer cu octeții bruți.