Skip to main content

快速刷新

快速刷新是 Next.js 中集成的 React 功能，可让你实时重新加载浏览器页面，同时在保存文件更改时保持临时客户端状态。它在 9.4 或更新版本的所有 Next.js 应用中默认启用。启用快速刷新后，大多数编辑应该在一秒钟内可见。

¥Fast refresh is a React feature integrated into Next.js that allows you live reload the browser page while maintaining temporary client-side state when you save changes to a file. It's enabled by default in all Next.js applications on 9.4 or newer. With Fast Refresh enabled, most edits should be visible within a second.

工作原理​

¥How It Works

  • 如果你编辑仅导出 React 组件的文件，快速刷新将仅更新该文件的代码，并重新渲染你的组件。你可以编辑该文件中的任何内容，包括样式、渲染逻辑、事件处理程序或效果。

    ¥If you edit a file that only exports React component(s), Fast Refresh will update the code only for that file, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.

  • 如果你编辑包含非 React 组件导出的文件，快速刷新将重新运行该文件以及导入该文件的其他文件。因此，如果 Button.js 和 Modal.js 都导入 theme.js，则编辑 theme.js 将更新这两个组件。

    ¥If you edit a file with exports that aren't React components, Fast Refresh will re-run both that file, and the other files importing it. So if both Button.js and Modal.js import theme.js, editing theme.js will update both components.

  • 最后，如果你编辑由 React 树外部的文件导入的文件，快速刷新将回退到执行完全重新加载。你可能有一个文件，它渲染 React 组件，但也导出由非 React 组件导入的值。例如，也许你的组件还导出一个常量，并且非 React 实用程序文件导入它。在这种情况下，请考虑将常量迁移到单独的文件并将其导入到两个文件中。这将重新启用快速刷新功能。其他情况通常也可以用类似的方法解决。

    ¥Finally, if you edit a file that's imported by files outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility file imports it. In that case, consider migrating the constant to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

错误恢复能力​

¥Error Resilience

语法错误​

¥Syntax Errors

如果在开发过程中出现语法错误，你可以修复它并重新保存文件。该错误将自动消失，因此你无需重新加载应用。你不会丢失组件状态。

¥If you make a syntax error during development, you can fix it and save the file again. The error will disappear automatically, so you won't need to reload the app. You will not lose component state.

运行时错误​

¥Runtime Errors

如果你犯了一个错误，导致组件内部出现运行时错误，你将看到上下文覆盖。修复错误将自动关闭叠加层，而无需重新加载应用。

¥If you make a mistake that leads to a runtime error inside your component, you'll be greeted with a contextual overlay. Fixing the error will automatically dismiss the overlay, without reloading the app.

如果渲染过程中没有发生错误，组件状态将被保留。如果在渲染过程中确实发生错误，React 将使用更新的代码重新安装你的应用。

¥Component state will be retained if the error did not occur during rendering. If the error did occur during rendering, React will remount your application using the updated code.

如果你的应用中有 误差边界（这对于生产中的正常失败来说是一个好主意），它们将在渲染错误后在下一次编辑时重试渲染。这意味着错误边界可能会阻止你始终重置为根应用状态。但是，请记住，错误边界不应该太细粒度。它们由 React 在生产中使用，并且应始终有意设计。

¥If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a rendering error. This means having an error boundary can prevent you from always getting reset to the root app state. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

局限性​

¥Limitations

快速刷新尝试在你正在编辑的组件中保留本地 React 状态，但前提是这样做是安全的。以下是你可能会在每次编辑文件时看到本地状态被重置的几个原因：

¥Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • 类组件不保留本地状态（只有函数组件和 Hook 保留状态）。

    ¥Local state is not preserved for class components (only function components and Hooks preserve state).

  • 除了 React 组件之外，你正在编辑的文件可能还有其他导出。

    ¥The file you're editing might have other exports in addition to a React component.

  • 有时，文件会导出调用高阶组件（如 HOC(WrappedComponent)）的结果。如果返回的组件是一个类，则其状态将被重置。

    ¥Sometimes, a file would export the result of calling a higher-order component like HOC(WrappedComponent). If the returned component is a class, its state will be reset.

  • 像 export default () => <div />; 这样的匿名箭头函数会导致快速刷新无法保留本地组件状态。对于大型代码库，你可以使用我们的 name-default-component 代码模式。

    ¥Anonymous arrow functions like export default () => <div />; cause Fast Refresh to not preserve local component state. For large codebases you can use our name-default-component codemod.

随着更多的代码库转移到函数组件和 Hook，你可以期望在更多情况下保留状态。

¥As more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

提示​

¥Tips

  • 默认情况下，快速刷新会保留函数组件（和 Hook）中的 React 本地状态。

    ¥Fast Refresh preserves React local state in function components (and Hooks) by default.

  • 有时你可能想要强制重置状态并重新安装组件。例如，如果你要调整仅在安装时发生的动画，这会很方便。为此，你可以在正在编辑的文件中的任意位置添加 // @refresh reset。该指令是文件的本地指令，并指示快速刷新在每次编辑时重新安装该文件中定义的组件。

    ¥Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

  • 你可以将 console.log 或 debugger; 放入你在开发过程中编辑的组件中。

    ¥You can put console.log or debugger; into the components you edit during development.

  • 请记住，导入区分大小写。当导入与实际文件名不匹配时，快速刷新和完全刷新都可能失败。例如，'./header' 与 './Header'。

    ¥Remember that imports are case sensitive. Both fast and full refresh can fail, when your import doesn't match the actual filename. For example, './header' vs './Header'.

快速刷新和钩子​

¥Fast Refresh and Hooks

如果可能，快速刷新会尝试在编辑之间保留组件的状态。特别是，只要你不更改 useState 和 useRef 的参数或 Hook 调用的顺序，它们就会保留其先前的值。

¥When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

具有依赖的钩子（例如 useEffect、useMemo 和 useCallback）将始终在快速刷新期间更新。在快速刷新发生时，它们的依赖列表将被忽略。

¥Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

例如，当你将 useMemo(() => x * 2, [x]) 编辑为 useMemo(() => x * 10, [x]) 时，即使 x（依赖）没有更改，它也会重新运行。如果 React 不这样做，你的编辑将不会反映在屏幕上！

¥For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

有时，这可能会导致意想不到的结果。例如，即使具有空依赖数组的 useEffect 仍会在快速刷新期间重新运行一次。

¥Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh.

然而，即使没有快速刷新，编写能够适应偶尔重新运行 useEffect 的代码也是一个很好的做法。它将使你以后更容易向其引入新的依赖，并且它由 React 严格模式 强制执行，我们强烈建议启用它。

¥However, writing code resilient to occasional re-running of useEffect is a good practice even without Fast Refresh. It will make it easier for you to introduce new dependencies to it later on and it's enforced by React Strict Mode, which we highly recommend enabling.