企业官网建设流程全解析

• 前端

ahooks 是一套高质量、可靠的 React Hooks 库，本指南以其官方介绍文档为主线，围绕「特性、安装、使用」三大核心环节展开：既讲清楚它在当前 React 项目中扮演的角色与六大核心特性，又结合仓库源码逐一印证这些特性背后的真实实现，并给出完整的包管理与导入实践。读完本文，你将掌握 ahooks 的选型依据、安装接入方式、入口导入路径，以及若干关键 Hooks（如 useRequest、useMemoizedFn）的源码级工作原理。

ahooks 是什么

ahooks，发音为 [eɪ hʊks]，是一套高质量可靠的 React Hooks 库。在现代 React 项目的研发过程中，一套好用的 React Hooks 库几乎是必不可少的公共基础设施——它把大量可复用的状态逻辑、副作用处理、DOM 交互能力沉淀为标准的 Hook API，让业务代码更聚焦、更易维护。ahooks 的定位正是成为这一基础设施的可靠选择。

从仓库结构看，ahooks 是一个 monorepo，核心源码位于 packages/hooks/src，主包名为ahooks；此外还有独立的use-url-state子包（位于 packages/use-url-state），用于将 URL query 与 React 状态双向同步。

核心特性：六点逐一解读

官方介绍文档将 ahooks 的核心特性概括为以下六点，这些特性并非空泛宣传，均能在仓库源码中找到对应实现。

1. 易学易用

ahooks 的 API 设计遵循 React Hooks 的直觉：每个 Hook 都是一个普通函数调用，返回值结构清晰。例如基础的useBoolean（源码）返回一个[state, actions]元组，其中actions提供setTrue、setFalse、set、toggle四个方法，无需记忆复杂的配置对象：

import { useBoolean } from 'ahooks'; const [state, { setTrue, setFalse, toggle }] = useBoolean(false);

从源码可以看到，useBoolean内部基于useToggle组合实现，并通过useMemo固定 actions 引用，保证性能的同时让调用方心智负担降到最低。

2. 支持 SSR

服务端渲染（SSR）场景下，useLayoutEffect等浏览器专属 API 会直接报错，ahooks 通过useIsomorphicLayoutEffect（源码）统一处理这类差异：

import { useLayoutEffect } from 'react'; import isBrowser from '../utils/isBrowser'; import noop from '../utils/noop'; const useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : noop;

其原理依赖 utils/isBrowser.ts 中的环境判断：

const isBrowser = !!( typeof window !== 'undefined' && window.document && window.document.createElement );

在浏览器环境使用useLayoutEffect，在服务端（无window/document）则退化为noop，从而让依赖该 Hook 的高级能力（如 useSize、useScroll 等）在 SSR 下安全运行。

3. 对输入输出函数特殊处理，避免闭包问题

闭包陷阱是 React 函数组件开发中的经典难题。ahooks 提供useMemoizedFn（源码）从根上解决：无论传入函数如何变化，它始终返回同一个引用稳定的函数，但该函数内部每次调用都会读取最新传入的函数引用，因此不会产生过期闭包：

const useMemoizedFn = <T extends noop>(fn: T) => { const fnRef = useRef<T>(fn); fnRef.current = useMemo<T>(() => fn, [fn]); // 保证引用最新 const memoizedFn = useRef<PickFunction<T>>(undefined); if (!memoizedFn.current) { memoizedFn.current = function (this, ...args) { return fnRef.current.apply(this, args); // 执行时读取最新函数 }; } return memoizedFn.current; // 引用永远稳定 };

配套的useLatest（源码）则是更底层的工具，用useRef始终持有最新值：

function useLatest<T>(value: T) { const ref = useRef(value); ref.current = value; return ref; }

此外，在开发环境下源码还内置了参数校验逻辑，例如useMemoizedFn在参数不是函数时会输出console.error提示，帮助开发者尽早发现问题（由 utils/isDev.ts 控制仅开发环境生效）。

4. 包含大量提炼自业务的高级 Hooks

这是 ahooks 最具竞争力的部分。以useRequest为例，它在 packages/hooks/src/useRequest 目录下由核心Fetch.ts、useRequest.ts、useRequestImplement.ts及 8 个插件（plugins）组成，集数据请求、加载状态、分页、轮询、防抖节流、缓存、重试、错误处理于一身。

从 useRequestImplement.ts 的源码可以看到其核心架构：

const { manual = false, ready = true, ...rest } = options; const fetchInstance = useCreation(() => { const initState = plugins.map((p) => p?.onInit?.(fetchOptions)).filter(Boolean); return new Fetch<TData, TParams>(serviceRef, fetchOptions, update, Object.assign({}, ...initState)); }, []); useMount(() => { if (!manual && ready) { const params = fetchInstance.state.params || options.defaultParams || []; fetchInstance.run(...params); } });

manual（手动触发，默认false）与ready（就绪后才自动请求，默认true）等关键参数正是在这里被解析并生效的。除useRequest外，同属高级 Hooks 的还有useAntdTable、useFusionTable、usePagination、useInfiniteScroll、useVirtualList、useReactive等，全部可在入口文件 packages/hooks/src/index.ts 中确认。

5. 包含丰富的基础 Hooks

基础层同样覆盖面广，覆盖状态类、生命周期类、DOM 交互类、副作用类等方方面面。以下仅列出入口文件（packages/hooks/src/index.ts）中导出的部分代表：

• 状态管理：useToggle、useBoolean、useCounter、useSetState、useMap、useSet、usePrevious、useHistoryTravel、useReactive、useResetState
• 生命周期：useMount、useUnmount、useUnmountedRef、useUpdate、useUpdateEffect、useUpdateLayoutEffect、useAsyncEffect、useTrackedEffect
• 副作用：useDebounce、useDebounceFn、useDebounceEffect、useThrottle、useThrottleFn、useThrottleEffect、useInterval、useTimeout、useRafInterval、useRafTimeout
• DOM 交互：useClickAway、useEventListener、useHover、useKeyPress、useLongPress、useMouse、useScroll、useFullscreen、useInViewport、useDrop/useDrag
• 存储与状态同步：useLocalStorageState、useSessionStorageState、useCookieState、useControllableValue、useEventEmitter、useResponsive、useExternal、useTitle、useFavicon、useNetwork、useWebSocket、useDocumentVisibility
• 性能与工具：useMemoizedFn、useLatest、useCreation、useDeepCompareEffect、useDeepCompareLayoutEffect、useSafeState、useGetState、useWhyDidYouUpdate、useSize、useVirtualList、useTextSelection、useMutationObserver、useFocusWithin、useInfiniteScroll

useMount（源码）的实现则体现了基础 Hooks 对边界情况的严谨处理——不仅校验参数必须是函数，还特别处理了返回 Promise 的情况，避免把 Promise 当作清理函数返回给useEffect：

useEffect(() => { const result = fn?.(); if (isThenable(result)) { return; // Promise 不作为 cleanup 返回 } return result; }, []);

6. 使用 TypeScript 构建，提供完整类型定义

ahooks 全量使用 TypeScript 编写，从 packages/hooks/package.json 可以看到发布产物包含lib（CJS）、es（ESM）、dist（UMD）三种格式，且types字段指向./lib/index.d.ts，sideEffects: false更利于 Tree Shaking。开发者在使用时能获得完整的类型提示与编译期校验，例如useRequest的Result<TData, TParams>泛型签名就定义在 packages/hooks/src/useRequest/src/types.ts 中。

安装

官方文档提供了四种主流的包管理器安装方式，任选其一即可：

$ npm install --save ahooks # or $ yarn add ahooks # or $ pnpm add ahooks # or $ bun add ahooks

从当前仓库的 packages/hooks/package.json 可以确认安装相关的几个关键信息：

• 当前版本：3.9.7；
• React 版本要求：peerDependencies声明支持react与react-dom的^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0，即只要你的项目使用 React 16.8+（Hooks 正式引入的版本）即可安全接入，兼容到 React 19；
• 运行时依赖：内部依赖dayjs（时间处理，供 useCountDown 等使用）、js-cookie（供 useCookieState 使用）、lodash、react-fast-compare（深度比较）、resize-observer-polyfill（供 useSize 等使用）、screenfull（供 useFullscreen 使用）等，安装时会自动随依赖解析带入；
• 协议：MIT 开源协议，可放心用于商业项目。

使用

安装完成后，从包名ahooks直接按需导入即可，官方文档给出的最小示例是：

import { useRequest } from 'ahooks';

入口文件 packages/hooks/src/index.ts 统一导出了全部 Hooks 及工具函数，除useRequest外还包含clearCache、CancelledError、isCancelledError（供 useRequest 缓存与取消场景使用）以及configResponsive（供 useResponsive 配置断点）。由于sideEffects: false，即便采用全量导入import * as ahooks from 'ahooks'，现代打包器也能通过 Tree Shaking 移除未使用的代码。

一个稍完整的实战示例，演示 useRequest 的自动请求与手动刷新：

import { useRequest } from 'ahooks'; import { getUser } from './api'; // 组件挂载后自动请求（manual 默认为 false） const { data, loading, error, refresh } = useRequest(getUser, { manual: false, ready: true, // 就绪后自动执行，默认即 true }); // 手动刷新 return <button onClick={refresh}>刷新</button>;

其中manual、ready、defaultParams等选项的解析逻辑，均可在 useRequestImplement.ts 源码中找到对应实现（例如开发环境下defaultParams非数组时会打印console.warn提示）。

Hooks 全景速览

为便于检索，下表按类别整理入口文件导出的常用 Hooks（完整清单以 packages/hooks/src/index.ts 为准）：

每个 Hooks 目录下都配套了__tests__测试用例（由 vitest 驱动，参见 packages/hooks/vitest.config.ts）、中英双语文档（index.zh-CN.md与index.en-US.md）以及可运行的 demo（demo/目录），例如useRequest的插件测试覆盖了缓存、轮询、防抖、节流、重试、窗口聚焦刷新等全部场景。

在线体验

官方介绍文档提供了 CodeSandbox 在线示例（demo for ahooks），你可以在浏览器中直接体验 useRequest 等核心 Hooks 的实际运行效果，无需本地搭建环境，非常适合初次接触时快速上手验证。

若想在本地阅读文档与运行示例，仓库采用 pnpm workspace 管理（见根目录 pnpm-workspace.yaml），可执行pnpm install安装依赖后运行相应开发脚本，但请注意本仓库为只读镜像，仅用于查看与学习。

进一步阅读

本文对应官方文档 docs/guide/index.zh-CN.md，英文版本见 docs/guide/index.en-US.md。想深入每一个 Hooks 的 API 与源码实现，可以直接浏览 packages/hooks/src 下对应目录；完整导出清单与版本信息，则可查阅 packages/hooks/src/index.ts 与 packages/hooks/package.json。

• 前端