Webpack 的 resolve.restrictions 选项用于给模块解析结果增加路径白名单校验。简单说，当 import 或 require 请求被解析成磁盘上的绝对路径后，Webpack 会拿这个路径与 restrictions 数组中每一条字符串或正则表达式进行比对。只要有一条匹配成功，模块就允许被加载；如果全部不匹配，构建就会直接报错。这个机制在大型项目、monorepo 以及需要严格隔离源码和第三方依赖的场景里很有用。
一、基本语法与路径匹配规则
restrictions 位于 webpack 配置的 resolve 字段下，类型为数组。数组项可以是绝对路径字符串，也可以是正则表达式。路径字符串的匹配采用前缀匹配，也就是说，解析出来的绝对路径必须以这个字符串开头，或者与它完全相等。这里要注意，路径字符串必须写成绝对路径，使用相对路径不会被正确处理，所以通常结合 Node.js 的 path.resolve 来生成。
下面这个配置将模块解析范围限制在当前项目的 src 目录，同时允许所有 node_modules 下的依赖。由于 node_modules 在 Windows 和 POSIX 系统上的分隔符不同，这里的正则使用字符组同时匹配正斜杠和反斜杠。
const path = require('path');
module.exports = {
resolve: {
restrictions: [
path.resolve(__dirname, 'src'),
/node_modules[\\/]/
]
}
};字符串匹配有一个容易忽略的细节：它是简单前缀匹配，不会自动判断目录边界。比如限制为 /project/src 时，/project/src2 这个不存在的误拼路径也会被允许。因此更严谨的做法是给路径末尾加上分隔符，或者使用带边界判断的正则。当然，如果目录名本身不会成为其他目录的前缀，直接使用 path.resolve 通常已经足够。
如果解析结果不在任何一条规则内，Webpack 会报告模块无法解析。比如只配置了 src 目录，然后代码中 import React from 'react'，由于 React 安装在项目根目录的 node_modules 里，它不会匹配 src 前缀，构建会失败。报错信息中通常会包含被限制的路径提示，方便定位是哪条 restriction 拦截了请求。
二、用 restrictions 隔离 monorepo 子包
在 pnpm workspace 或 Yarn workspaces 管理的 monorepo 中，多个包共享同一个仓库，但它们的构建往往是独立的。如果 packages/a 的代码通过相对路径 import '../../../packages/b/src/index' 直接引用另一个包，就会绕过包管理器的依赖声明机制，造成隐式耦合。restrictions 可以把每个包的构建解析范围锁死在自己的源码目录和 node_modules 中，迫使跨包引用必须走依赖声明。
假设 monorepo 根目录有 node_modules，packages 下分别是 a 和 b，两个包都有自己的 src 目录和独立的 webpack.config.js。可以把 packages/a 的 webpack 配置写成：
const path = require('path');
module.exports = {
resolve: {
restrictions: [
path.resolve(__dirname, 'src'),
/node_modules[\\/]/
]
}
};这样一来，packages/a/src/index.js 中写 import '../../b/src/index' 时，虽然文件真实存在，但由于它落在 packages/b/src 而不是 packages/a/src 或 node_modules 下，Webpack 会直接报错。正确做法是在 packages/a/package.json 中声明 workspace 依赖 "@scope/b": "workspace:*"，然后通过包名引入。node_modules 中的符号链接会指向 packages/b，路径满足 node_modules 规则，就能正常构建。
这种限制也带来了额外好处：每个包的构建产物不会因为文件系统变动而意外包含无关代码，构建边界更清晰。对于需要发布 npm 包的 monorepo 尤其重要，它能防止把开发时的相对路径引用带进发布逻辑。
三、与 alias、modules 的协作关系
Webpack 的解析流程中，alias 和 modules 会在比较早的阶段介入请求改写和查找目录，而 restrictions 更像是最终的安全校验。无论请求经过了 alias 替换，还是通过 modules 指定目录找到了文件，只要最终解析出的绝对路径不满足 restrictions，就会被拒绝。理解这一点可以避免一些配置之间的误解。
例如下面配置里，@utils 被指向 src/utils 目录：
const path = require('path');
module.exports = {
resolve: {
alias: {
'@utils': path.resolve(__dirname, 'src/utils')
},
modules: [
path.resolve(__dirname, 'src/components'),
'node_modules'
],
restrictions: [
path.resolve(__dirname, 'src'),
/node_modules[\\/]/
]
}
};这里 alias 指向的最终路径是 src/utils，它落在 src 目录下，所以可以正常解析。node_modules 目录被显式列出，也满足第二条正则规则。如果以后有人把 alias 指到 ../shared/utils，而 shared 不在 restrictions 白名单内，构建就会立刻失败。这实际上把路径控制从“口头约定”变成了强制约束。
modules 也是同理。当项目使用 resolve.modules 把某几个目录设为无路径引用查找目录时，这些目录必须同时被 restrictions 覆盖。比如上面的 src/components 如果不在 src 下，模块解析成功但最终也会被 restrictions 拦截。建议在调整 resolve.modules 时同步更新 restrictions，不然会出现明明文件找得到、构建却报错的怪现象。
调试这类问题时，可以执行 webpack 并加上 --stats-error-details 参数，输出内容会包含解析到哪个具体路径以及被哪条限制拦截。临时注释掉 restrictions 也能快速判断是不是该选项导致的问题，但修复时应当调整白名单，而不是移除限制。
四、正则限制的高级用法与性能建议
正则表达式让 restrictions 不仅能做目录前缀控制，还能做更细粒度的过滤。常见需求是允许 src 目录下的所有文件，但排除某些指定子目录，比如 src/private 或 src/legacy。可以构造一个带负向前瞻的正则，把整个 src 目录作为基础，再排除特定片段。
const path = require('path');
const srcRoot = path.resolve(__dirname, 'src');
// 将路径中的特殊字符转义后拼接正则
const escapedRoot = srcRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
module.exports = {
resolve: {
restrictions: [
new RegExp('^' + escapedRoot + '($|[\\\\/])(?!private[\\\\/])'),
/node_modules[\\/]/
]
}
};这段代码先对 srcRoot 中的特殊字符做转义，再拼上路径分隔符边界，最后通过负向前瞻排除 private 子目录。这样 import 指向 src/utils 可以通过，指向 src/private/debug 则会被拦下。虽然这种写法稍显复杂，但在需要精细控制源码内部模块可见性时很好用。
性能方面，restrictions 对构建时间的影响通常很小。它是在文件已经被解析到绝对路径之后进行的字符串或正则比较，不涉及额外的文件系统查找。相对于 resolver 本身大量的 stat 调用和读取 package.json 的 IO 操作，这部分计算开销可以忽略。但如果数组里写了大量复杂的正则，每个模块都要逐一跑完所有规则，大型项目中还是要保持正则数量可控。优先用字符串前缀匹配，再用少量正则处理特殊情况，是更稳妥的做法。
总的来说，resolve.restrictions 更像一道最后的防线，它不负责寻找模块，也不负责改写请求，而是确保最终加载的文件确实位于预期目录中。把它用在需要严格控制源码边界、防止误引用的 monorepo 或大型应用中，可以显著降低依赖管理风险。不过它只控制路径，不控制包名，所以无法替代 ESLint 插件、依赖审计工具或 import 级别的限制。配合 alias、modules 与合理的目录结构，才能发挥最大价值。
Webpackresolve.restrictions模块解析修改时间：2026-09-25 10:51:34