如何在JavaScript项目中将自定义模块设为全局可用，实现类似npm生态的模块名导入而非路径导入？

我之前在做项目的时候也遇到过这个需求——不想每次写长长的相对路径，就像用npm包那样直接用模块名导入自己的工具库，折腾了几种靠谱的方案，现在整理给你：

方法1：用package.json的exports字段（推荐，ES模块友好） #

这是目前Node.js官方推荐的方式，不管是CommonJS还是ES模块都能完美支持。

在项目根目录的package.json里添加exports字段，直接映射你的模块名称到实际文件路径：

{
  "name": "your-project-name",
  "type": "module", // 如果是ES模块项目，记得加这个
  "exports": {
    "custom-modules": "./src/utils/custom-modules.js"
  }
}

配置完之后，不管你在项目的哪个文件里，都可以直接这样导入：

// ES模块语法
import CustomModule from "custom-modules";

// CommonJS语法（如果没加"type": "module"）
const CustomModule = require("custom-modules");

如果你的自定义模块有多个子模块，还可以扩展exports来支持子路径导入：

"exports": {
  "custom-modules": "./src/utils/custom-modules.js",
  "custom-modules/helpers": "./src/utils/helper-functions.js"
}

这样就能用import { formatDate } from "custom-modules/helpers";来导入子模块了。

方法2：使用NODE_PATH环境变量（传统CommonJS方式） #

这是比较旧的方案，只适合CommonJS项目（ES模块不支持），但胜在简单。

假设你把自定义模块都放在src/modules目录下，只需要设置NODE_PATH指向这个目录：

• Mac/Linux 终端：

  export NODE_PATH=./src/modules
  

• Windows 命令行：

  set NODE_PATH=./src/modules
  

或者更方便的是在package.json的scripts里配置，避免每次手动设置：

"scripts": {
  "start": "NODE_PATH=./src/modules node index.js"
}

之后你就可以直接用模块名导入，比如const CustomModule = require("custom-modules");

如果你的项目用了Webpack、Vite这类前端构建工具，就需要在工具配置里设置别名。

Webpack 配置 #

在webpack.config.js里添加resolve.alias：

const path = require('path');

module.exports = {
  // ...其他Webpack配置
  resolve: {
    alias: {
      "custom-modules": path.resolve(__dirname, "src/utils/custom-modules.js")
    }
  }
};

如果是TypeScript项目，还要在tsconfig.json里同步配置paths，让IDE能识别别名：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "custom-modules": ["./src/utils/custom-modules.js"]
    }
  }
}

Vite 配置 #

Vite的配置类似，在vite.config.js里设置resolve.alias：

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      'custom-modules': path.resolve(__dirname, './src/utils/custom-modules.js')
    }
  }
});

同样，TypeScript项目要在tsconfig.json里配置paths，和Webpack的TS配置一样。

• 如果你用的是ES模块，一定要确保package.json里有"type": "module"，否则Node.js会把.js文件当作CommonJS处理，可能出现语法错误。
• 用exports字段时，路径要从package.json所在的根目录开始写，别搞错相对路径。
• 配置完构建工具的别名后，建议重启一下IDE，这样自动补全和语法提示才能正常工作。

内容的提问来源于stack exchange，提问作者Shazil Sattar