Webpack与TypeScript项目路径别名配置失效，求助排查

项目结构：

src/
src/common/components/
src/common/constants/
src/common/hooks/

使用Webpack作为构建工具，TypeScript开发。先尝试在Webpack配置中设置resolve.alias：

import { fileURLToPath } from "node:url";

import { CleanWebpackPlugin } from "clean-webpack-plugin";
import { EsbuildPlugin } from "esbuild-loader";
import MiniCssExtractPlugin from "mini-css-extract-plugin";
import path from "path";
import rehypeSlug from "rehype-slug";
import webpack from "webpack";

import deps from "./package.json" assert { type: "json" };

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const { ModuleFederationPlugin } = webpack.container;
export default {
    entry: "./src/index.tsx",
    output: {
        filename: "[name].[fullhash].js",
        path: path.resolve(__dirname, "./dist"),
    },
    experiments: {
        topLevelAwait: true,
    },
    resolve: {
        extensions: [".tsx", ".ts", ".js", ".jsx"],
        alias: {
            Common: path.resolve(__dirname, "src/common"),
        }
    },
    // 省略其他配置
};

使用如下导入时出现错误：

import text from "Common/constants/texts";

错误信息：

Cannot find module 'Common/constants/texts' at webpackMissingModule

之后尝试在TypeScript的compilerOptions中配置：

"baseUrl": "src",
"paths": {
  "@common/*": ["src/common/*"],
}

但依旧无效，请问配置哪里出错了？

一、Webpack别名配置的核心问题 #

你当前Webpack的alias配置逻辑没错，但大小写不匹配：别名用了Common（首字母大写），但项目实际目录是common（全小写）。在区分大小写的系统（如Linux/macOS）中，Webpack会严格匹配路径大小写，导致找不到文件。修改为全小写的别名即可：

resolve: {
    extensions: [".tsx", ".ts", ".js", ".jsx"],
    alias: {
        common: path.resolve(__dirname, "src/common"),
    }
},

对应导入语句改为：

import text from "common/constants/texts";

二、TypeScript路径配置的错误 #

你在tsconfig.json里的paths配置冗余了：当baseUrl设为src时，paths的目标路径不需要再加src/——因为baseUrl已经把根路径指向了src目录。正确配置应为：

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

此时@common/*会自动映射到src/common/*。

三、必须同步Webpack与TypeScript的别名 #

TypeScript的paths仅用于IDE语法提示和tsc编译，Webpack并不识别这个配置。如果想用@common这类自定义别名，必须在Webpack里同步配置：

resolve: {
    extensions: [".tsx", ".ts", ".js", ".jsx"],
    alias: {
        "@common": path.resolve(__dirname, "src/common"),
    }
},

这样导入时使用@common/constants/texts，TypeScript和Webpack都能正确解析路径。

四、额外检查项 #

1. 确认Webpack加载器读取了正确的tsconfig.json：如果用ts-loader或esbuild-loader，需确保配置中指定了你的tsconfig.json路径。
2. 清理Webpack缓存：缓存可能导致配置不生效，执行npx webpack --clear-cache或删除node_modules/.cache目录重试。

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