node 运行时识别 @app 别名需借助 module-alias：安装后在入口文件首行执行 require('module-alias/register')，并在 package.json 中配置 _modulealiases 字段映射 @app 到实际路径（如 "@app": "src/app"），且注册必须早于任何 require 或 import。
Node 运行时怎么识别 @app 这类别名
Node 默认不认 @app 这种路径别名，直接 require('@app/utils') 会报 Error: Cannot find module '@app/utils'。必须靠第三方模块注册运行时解析逻辑。
最轻量、兼容性最好的方案是用 module-alias：
- 安装：
npm install module-alias --save-dev（开发时用，生产可删） - 在项目入口文件（如
index.js或server.js）顶部第一行写：require('module-alias/register') - 在
package.json根级加字段："_moduleAliases"，值为对象，键是别名，值是相对项目根的路径，例如："@app": "src/app"
注意：这个注册必须在任何 require 或 import 之前执行；如果用了 esbuild 或 ts-node 启动，得改用它们各自的别名支持方式（比如 ts-node --loader ts-node/esm + tsconfig.json 的 paths），module-alias 在 ESM 模式下不生效。
VSCode 跳转和补全为什么还是找不到 @app
就算 Node 能跑通，VSCode 编辑器本身不读 package.json 里的 _moduleAliases，所以 Ctrl+Click 会失败、自动补全也不出现 @app 下的文件。
解决方法是加 jsconfig.json（JS 项目）或 tsconfig.json（TS 项目），且必须包含 baseUrl 和 paths：
-
baseUrl设为"."（项目根） -
paths写成对象，键和package.json里一致，但值要带/*，例如："@app/*": ["src/app/*"] - 确保文件放在项目根目录，且没有拼错名字（不是
jsconfig.js，也不是jsconfig.json5）
改完后重启 VSCode 窗口（不是重载，是完全关闭再打开），否则语言服务不会重新加载配置。
launch.json 调试时别名失效怎么办
调试器启动的是独立 Node 进程，它不自动继承你代码里 require('module-alias/register') 的效果——尤其当你用 program 指向 dist/index.js 这类构建后入口时，register 那行根本没执行。
两个可靠做法：
- 把
module-alias注册逻辑提前到构建产物里：比如用esbuild的banner插件，在生成的 JS 文件开头注入require('module-alias/register'); - 或者更简单：调试时不用构建产物，直接调试源码，
launch.json中设"program": "${workspaceFolder}/src/index.ts"，并确保ts-node已全局安装，同时runtimeArgs加上--loader ts-node/esm（ESM 项目）或-r ts-node/register（CommonJS）
别在 launch.json 里硬写 runtimeExecutable 指向某个 Node 可执行文件来“绕过”这个问题——那只是换了个地方失败。
Webpack 打包时别名不生效的常见漏点
Webpack 默认不认识 package.json 里的 _moduleAliases，也忽略 jsconfig.json。必须显式配 resolve.alias。
- 路径必须用
path.resolve()，不能写相对路径字符串，例如："@app": path.resolve(__dirname, 'src/app') - 如果项目用 ESM 输出（
type: "module"），注意 Webpack 5.12+ 才完整支持 ESM alias，旧版本需加exports字段或降级用 CommonJS - 别忘了在
module.rules里处理对应扩展名，比如.ts文件要配ts-loader或swc-loader，否则 alias 解析了，但编译阶段就卡住
真正容易被忽略的是：VSCode 的智能提示、Node 运行时、Webpack 构建、Debugger 四者用的是四套独立的路径解析机制，缺一不可，且各自配置互不继承。别指望配一处就全好。
