Webpack-dev-server 路径重写技巧

本文深入解析了如何利用 webpack-dev-server 的 `historyApiFallback.rewrites` 功能，以零网络开销、高可靠性的方式实现跨路径静态资源的精准 URL 重写（如将 `/subpath/locales/en.json` 本地直连到 `src/locales/en.json`），彻底规避传统 proxy 方案因 DNS、HTTPS 证书、防火墙等引发的 ETIMEDOUT/EHOSTUNREACH 等顽固网络错误；通过清晰的正则配置、静态目录映射与关键注意事项说明，手把手教你构建调试友好、语义明确、完全脱离后端依赖的本地开发体验——原来，最稳健的“代理”，根本不需要发一次真实请求。

本文详解如何使用 historyApiFallback.rewrites 替代代理（proxy）实现跨路径的静态资源 URL 重写，解决 /subpath/locales/file.json → /locales/file.json 的精准映射问题，并规避代理引发的 ETIMEDOUT/EHOSTUNREACH 网络异常。

在前端开发中，常需将形如 https://some.domain.com/subpath/locales/en.json 的请求，不经过网络转发、零延迟地映射到本地静态文件（如 src/locales/en.json）。初看容易想到用 devServer.proxy，但实际它本质是 HTTP 反向代理——会真实发起一次新请求到目标服务器，不仅引入网络开销，更易因 DNS、证书、防火墙或 hosts 配置异常导致 ETIMEDOUT 或 EHOSTUNREACH 错误（正如你遇到的 HPM Error）。

真正符合“路径重写 + 静态服务”语义的方案，是 historyApiFallback.rewrites ——它工作在 dev-server 内部请求路由层，不发新 HTTP 请求，仅做路径解析与内部重定向，性能高、调试清晰、无跨域/证书干扰。

✅ 正确配置：使用 historyApiFallback.rewrites

const path = require('path');

module.exports = {
  // ... 其他配置
  devServer: {
    port: 443,
    server: { type: 'https' },
    compress: true,
    allowedHosts: 'all',
    headers: {
      'Access-Control-Allow-Origin': '*',
    },
    client: {
      webSocketURL: 'auto://some.domain.com/ws',
    },

    // ✅ 核心：用 historyApiFallback 实现纯路径重写
    historyApiFallback: {
      rewrites: [
        {
          // 匹配任意前缀下的 /locales/**.json，例如：
          // /app/locales/zh.json → 提取 'zh.json'
          // /v2/api/locales/en-US.json → 提取 'en-US.json'
          from: /^\/[^/]+\/locales\/(.+\.json)$/i,
          to: ({ parsedUrl }) => {
            const filename = path.basename(parsedUrl.pathname);
            return `/locales/${filename}`;
          }
        }
      ],
      // ⚠️ 注意：启用 rewrites 后，必须禁用默认 fallback 行为
      // 否则未匹配的请求仍会 fallback 到 index.html，造成干扰
      disableDotRule: true
    },

    // ✅ 静态资源目录映射：让 /locales/* 指向本地文件
    static: [
      {
        directory: path.join(__dirname, 'src', 'locales'),
        publicPath: '/locales/',
        serveIndex: false, // 禁用目录列表（避免看到 listing directory）
        watch: true
      }
    ]
  }
};

? 为什么比 proxy 更可靠？

⚠️ 关键注意事项

• 正则必须精确：from 使用 ^\/[^/]+\/locales\/(.+\.json)$ 确保只匹配含一级路径前缀（如 /subpath/locales/xxx.json），避免误伤 /locales/xxx.json 原生路径。
• to 函数返回绝对路径：必须以 / 开头（如 /locales/en.json），否则会被视为相对路径导致 404。
• static.publicPath 必须与 to 返回路径一致：二者共同构成“请求 URL → 本地文件”的映射链。
• 禁用 serveIndex：防止访问 /locales/ 时返回目录列表页（即你最初遇到的 listing directory 问题）。
• disableDotRule: true：避免 . 开头文件被忽略，确保 .json 文件可被正确识别。

✅ 验证是否生效

启动服务后，在浏览器或终端执行：

curl -v https://some.domain.com/subpath/locales/en.json

✅ 成功时应返回 src/locales/en.json 的原始内容，HTTP 状态码为 200，且响应头中 Content-Type: application/json。
❌ 若仍报错，请检查：

• src/locales/en.json 文件是否存在；
• publicPath: '/locales/' 末尾斜杠是否遗漏；
• 正则是否匹配了你的实际 URL（可用 regex101.com 在线测试）。

? 延伸建议：若需支持多语言目录嵌套（如 /locales/en-US/common.json），可升级正则为 /^\/[^/]+\/locales\/(.*)$/ 并在 to 中保留完整子路径：return/locales/${RegExp.$1}`，再配合static.directory指向根locales` 目录即可。

通过 historyApiFallback.rewrites，你获得的不仅是路径重写能力，更是一种声明式、零副作用、贴近开发直觉的静态资源服务方式——它让 webpack-dev-server 回归其本质：一个专注前端开发体验的轻量级开发服务器。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Webpack-dev-server 路径重写技巧》文章吧，也可关注golang学习网公众号了解相关技术文章。