specifier = "@/components/Button"

specifier
    ↓
真实模块

ESM_RESOLVE(specifier, parentURL)

import "./foo.js"
import "../foo.js"
import "/app/foo.js"

import react from "react"

import db from "#db"

import x from "file:///app/a.js"

import x from "@/utils"

Module Not Found

import Button from "@/components/Button"

resolve: {
  alias: {
    "@": "/project/src"
  }
}

@/components/Button

/project/src/components/Button

旧 specifier
    ↓
新 specifier

resolve: {
  alias: {
    "@": path.resolve(__dirname, "src")
  }
}

import x from "@/utils/request"

@ -> /project/src

/project/src/utils/request

Webpack Alias
Vite Alias
Rspack Alias

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

VSCode 正常
TypeScript 正常
Node 运行失败

paths

类型检查
IDE 跳转
编译阶段

tsconfig.json

{
  "paths": {}
}

import "@/utils"

Webpack Alias
Vite Alias
Rspack Alias
Node Loader

export async function resolve(
  specifier,
  context,
  nextResolve
)

export async function resolve(
  specifier,
  context,
  nextResolve
) {
  if (specifier.startsWith("@/")) {
    return {
      url: pathToFileURL(
        path.resolve(
          process.cwd(),
          "src",
          specifier.slice(2)
        )
      ).href,
      shortCircuit: true
    }
  }

  return nextResolve(specifier, context)
}

import x from "@/utils"

file:///project/src/utils.js

node_modules

import React from "react"

<script type="importmap">
{
  "imports": {
    "react": "/vendor/react.js"
  }
}
</script>

import React from "react"

react
    ↓
/vendor/react.js

Webpack Alias
Vite Alias
Rspack Alias
TS Paths
Node Loader
Import Map

specifier
    ↓
mapping
    ↓
new specifier
    ↓
real URL

映射规则存放的位置不同

import App from "./App"

specifier
    ↓
resolver
    ↓
real module

App.tsx

App.tsx
    ↓
Button.tsx
    ↓
request.ts
    ↓
...

Module Graph