diff --git a/packages/document/builder-doc/docs/en/guide/faq/hmr.md b/packages/document/builder-doc/docs/en/guide/faq/hmr.md index 53c32ac21650..a87531f33ef3 100644 --- a/packages/document/builder-doc/docs/en/guide/faq/hmr.md +++ b/packages/document/builder-doc/docs/en/guide/faq/hmr.md @@ -1,5 +1,44 @@ # HMR FAQ +### How to troubleshooting HMR ineffective issues? + +There are several possible reasons why HMR may not be work. This document will cover most common causes and provide guidance for troubleshooting. Please refer to the following content for troubleshooting. + +Before starting the troubleshooting process, it is helpful to have a basic understanding of how HMR works: + +:::tip HMR Principle + +1. The browser establishes a WebSocket connection with the development server for real-time communication. +2. Whenever the development server finishes recompiling, it sends a notification to the browser via the WebSocket. The browser then sends a `hot-update.xxx` request to the development server to load the newly compiled module. +3. After receiving the new module, if it is a React project, React Refresh, an official React tool, is used to update React components. Other frameworks have similar tools. + +::: + +After understanding the principle of HMR, you can follow these steps for basic troubleshooting: + +#### 1. Check the WebSocket Connection + +Open the browser console and check for the presence of the `[HMR] connected.` log. + +- If it is present, the WebSocket connection is working correctly. You can continue with the following steps. +- If it is not present, open the Network panel in Chrome and check the status of the `ws://[host]:[port]/webpack-hmr` request. If the request is failed, this indicates that the HMR failed because the WebSocket connection was not successfully established. + +There can be various reasons why the WebSocket connection fails to establish, such as using a network proxy that prevents the WebSocket request from reaching the development server. You can check whether the WebSocket request address matches your development server address. If it does not match, you can configure the WebSocket request address using [tools.devServer.client](/api/config-tools.html#client). + +#### 2. Check the hot-update Requests + +When you modify the code of a module and trigger a recompilation, the browser sends several `hot-update.json` and `hot-update.js` requests to the development server to fetch the updated code. + +You can try modifying a module and inspect the content of the `hot-update.xxx` requests. If the content of the request is the latest code, it indicates that the hot update request is working correctly. + +If the content of the request is incorrect, it is likely due to a network proxy. Check whether the address of the `hot-update.xxx` request matches your development server address. If it does not match, you need to adjust the proxy rules to route the `hot-update.xxx` request to the development server address. + +#### 3. Check for Other Causes + +If the above two steps do not reveal any issues, it is possible that other factors are causing the HMR to fail. For example, it could be that the code does not meet React's requirements for HMR. You can refer to the following questions for further troubleshooting. + +--- + ### HMR not working when external React? To ensure that HMR works properly, we need to use the development builds of React and ReactDOM. diff --git a/packages/document/builder-doc/docs/zh/guide/advanced/hmr.md b/packages/document/builder-doc/docs/zh/guide/advanced/hmr.md index 5bd4ed75ffbc..3b4d8ff79964 100644 --- a/packages/document/builder-doc/docs/zh/guide/advanced/hmr.md +++ b/packages/document/builder-doc/docs/zh/guide/advanced/hmr.md @@ -1,6 +1,6 @@ -# 模块热替换 +# 模块热更新 -模块热替换（HMR - hot module replacement）功能会在应用程序运行过程中，替换、添加或删除模块，而无需重新加载整个页面。主要是通过以下几种方式，来显著加快开发速度： +模块热更新（HMR - hot module replacement）功能会在应用程序运行过程中，替换、添加或删除模块，而无需重新加载整个页面。主要是通过以下几种方式，来显著加快开发速度： - 保留在完全重新加载页面期间丢失的应用程序状态。 - 只更新变更内容，以节省宝贵的开发时间。 diff --git a/packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx b/packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx index 0e7222e6a750..2f0838b2dc88 100644 --- a/packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx +++ b/packages/document/builder-doc/docs/zh/guide/advanced/rspack-start.mdx @@ -184,7 +184,7 @@ Rspack 默认会使用 SWC 进行转译和压缩，因此，在启用 Rspack 构 | Babel 插件 | Rspack 配置项 | Builder 配置项 | | ----------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | @babel/preset-env | [builtins.presetEnv](https://www.rspack.dev/zh/config/builtins.html#builtinspresetenv) | [设置浏览器范围](/guide/advanced/browserslist.html)、
[浏览器兼容性](/guide/advanced/browser-compatibility.html) | -| @babel/preset-react | [builtins.react](https://www.rspack.dev/zh/config/builtins.html#builtinsreact) | [模块热替换](/guide/advanced/hmr.html) | +| @babel/preset-react | [builtins.react](https://www.rspack.dev/zh/config/builtins.html#builtinsreact) | [模块热更新](/guide/advanced/hmr.html) | | @emotion/babel-plugin | [builtins.emotion](https://www.rspack.dev/zh/config/builtins.html#builtinsemotion) | 暂无 | | babel-plugin-import | [builtins.pluginImport](https://www.rspack.dev/zh/config/builtins.html#builtinspluginimport) | [source.transformImport](/api/config-source.html#sourcetransformimport) | | babel-plugin-lodash | 暂无 | 暂无 | diff --git a/packages/document/builder-doc/docs/zh/guide/faq/hmr.md b/packages/document/builder-doc/docs/zh/guide/faq/hmr.md index 4ce8556f8e4f..d4240dacc25a 100644 --- a/packages/document/builder-doc/docs/zh/guide/faq/hmr.md +++ b/packages/document/builder-doc/docs/zh/guide/faq/hmr.md @@ -1,5 +1,44 @@ # 热更新问题 +### 热更新不生效，如何排查？ + +热更新不生效有很多种可能的原因，在这篇文档中会介绍大部分常见的原因，你可以参照以下内容进行排查。 + +在开始排查之前，请简单了解一下热更新的原理： + +:::tip 热更新原理 + +1. 浏览器和开发服务器建立一个 Web Socket 连接，用于实时通信。 +2. 当开发服务器每次重新编译完成后，会通过 Web Socket 通知浏览器，浏览器向开发服务器发送 `hot-update.xxx` 请求，从而加载编译后的新模块。 +3. 当浏览器收到新的模块后，如果是 React 项目，则会通过 React 官方的 React Refresh 来更新 React 组件，其他框架也是类似。 + +::: + +了解完热更新的原理后，你可以按照以下步骤来进行基本的排查： + +#### 1. 检查 Web Socket 连接 + +打开浏览器的控制台，查看是否有 `[HMR] connected.` 日志。 + +- 如果有，说明 Web Socket 连接正常，请继续检查后续步骤。 +- 如果没有，请打开 Chrome 的 Network 面板，查看 `ws://[host]:[port]/webpack-hmr` 的请求状态，若请求异常，说明热更新失败的原因是 Web Socket 请求没有建立成功。 + +Web Socket 请求没有建立成功的原因可能有很多种，例如开启了网络代理，导致 Web Socket 请求没有正确发送到开发服务器。你可以检查 Web Socket 请求的地址是否为你的开发服务器地址，如果不是，则可以通过 [tools.devServer.client](/api/config-tools.html#client) 来配置 Web Socket 请求的地址。 + +#### 2. 检查 hot-update 请求 + +当你修改一个模块的代码，并触发重新编译后，浏览器会向开发服务器发送若干个 `hot-update.json` 和 `hot-update.js` 请求，用于获取更新后的代码。 + +你可以尝试修改一个模块并检查 `hot-update.xxx` 请求的内容，如果请求的内容是最新的代码，说明热更新的请求正常。 + +如果请求的内容错误，大概率也是由于开启了网络代理，请检查 `hot-update.xxx` 请求的地址是否为你的开发服务器地址，如果不是，则需要调整代理规则，将 `hot-update.xxx` 请求代理到开发服务器地址。 + +#### 3. 检查其他原因 + +如果以上两个步骤都没有问题，那么可能是其他原因导致的热更新失败，比如没有符合 React 对热更新的要求，你可以参考下列的问题进行排查。 + +--- + ### 打包时 external React 后，热更新不生效？ 为了保证热更新生效，我们需要使用 React 和 ReactDOM 的开发环境产物。 diff --git a/packages/document/builder-doc/docs/zh/guide/features.mdx b/packages/document/builder-doc/docs/zh/guide/features.mdx index 82098b6f309f..ce81a9ab2bc8 100644 --- a/packages/document/builder-doc/docs/zh/guide/features.mdx +++ b/packages/document/builder-doc/docs/zh/guide/features.mdx @@ -64,7 +64,7 @@ | 功能 | 描述 | 相关链接 | | ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| React Refresh | 默认支持 React Refresh 热更新 | | +| React Refresh | 默认支持 React Refresh 热更新 | | | SVG 转 React 组件 | 默认支持在 React 组件中引用 SVG 作为组件 | | | Vue 3 SFC 编译 | 可选功能，开启 Vue 3 SFC 单文件组件编译 | | | Vue 3 JSX 编译 | 可选功能，开启 Vue 3 JSX 语法编译 | |