# @animus-ui/next-plugin 中文文档

规范地址：https://npmcn.com/package/%40animus-ui/next-plugin/

版本：0\.1\.87
npm 元数据更新时间：2026-10-24T04:20:07.373Z
中文译文更新时间：2026-11-06T04:53:43.769Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40animus-ui/next-plugin
原文对照：https://npmcn.com/package/%40animus-ui/next-plugin/?lang=original
项目主页：https://github.com/codecaaron/animus/tree/main/packages/next-plugin#readme
源码仓库：https://github.com/codecaaron/animus

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：194 kB，41 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：1 个
- peer 依赖：next \>=15 \<17，webpack \>=5 \<6，@animus-ui/layergate 0\.1\.87
- 首次发布：2026-03-31T20:48:43.091Z
- 最新版本发布：2026-10-24T04:20:06.915Z
- 近 30 天下载量：6619（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：101（近 12 个月 101 个）

## 中文简介

Animus 静态 CSS 提取 Next.js (webpack)

## 安装

```sh
npm install @animus-ui/next-plugin
```

也可以使用：`pnpm add @animus-ui/next-plugin`、`yarn add @animus-ui/next-plugin`、`bun add @animus-ui/next-plugin`

## README

# @animus-ui/下个插图

Next.js(15和16)的静态CSS提取. 环绕 `next.config` 整合Animus提炼管道——网络包装和涡轮包装.

## 安装

```bash
npm install @animus-ui/next-plugin @animus-ui/system
```

## 设置

```tsx
// next.config.mjs
import { withAnimus } from '@animus-ui/next-plugin';

const nextConfig = {
  // your existing Next.js config
};

export default withAnimus({
  system: './src/ds.ts',
})(nextConfig);
```

## 涡轮包装

Turbopack 支持在进程运行时自动激活 涡轮包装`next dev --turbopack`,或下16个涡轮包装 默认)——不需要配置更改. `withAnimus(...)(nextConfig)` 接下来 返回配置函数:下一个调用其相位,并提取运行 在它解决之前。 仅 `next dev` 分析开发模式并启动 重新分析源变化的监视器; `next build` p. 每个文件 用生成的无国籍装载器进行转换 `.animus/` 文物. 配置图 `paths` 化名是荣誉的.

应用期望对象的配置包件, 如 `withMDX`,改为 `nextConfig` 在传递给 `withAnimus`数字 : `withAnimus(options)(withMDX(nextConfig))`外部应用的包装器 将配置复制到新对象中,保留自己的密钥并删除 Animus 的密钥.

如果您的配置是其自身的函数, 请通过 Next 的相 :

```tsx
export default (phase: string) =>
  withAnimus({ system: './src/ds.ts', phase })(nextConfig);
```

也可以等待结果,如: `{ ...(await withAnimus(options)(nextConfig)) }`没有阶段,那么 读取 `NODE_ENV=development` 作为 `next dev` 和一切作为建筑。 A 类 `next.config.ts` 指定 `module.exports = withAnimus(...)(...)` 实值 等待同样的方法 当下一个编译它,所以写 `export default`,或 从配置函数通过相位.

因为 `next.config` 仅在第一次提取后解决,源 parser 无法在启动时在任何监视器存在之前拒绝配置 : 修复语法错误并再次启动 Next。 一旦监视器运行,一个后 语法错误保留最后公布的文物,并保持进一步编辑,直到 文件解析,然后一起出版.

明确控制它与 `turbopack` 选项 :

```tsx
export default withAnimus({
  system: './src/ds.ts',
  turbopack: { mode: 'auto' }, // 'auto' (default) | 'on' | 'off'
})(nextConfig);
```

在网络包装下`next dev` 编号 : `next build` 15号或 `--webpack` 第16条) 插件行为与以前完全相同 .

## 第三方样式表

图书馆的平面 CSS 外部任意 `@layer` 击败每个Animus层. 与 `quarantine`, (中文(简体) ), [`@animus-ui/layergate`](https://npmcn.com/package/%40animus-ui/layergate/README.md) 装入 `anm-vendor`在Animus的下面一层 所以Animus的风格就赢了 animus 无设置时, 库仍然适用 :

```bash
npm install -D @animus-ui/layergate
```

```tsx
export default withAnimus({
  system: './src/ds.ts',
  quarantine: {
    sheets: ['react-grid-layout/css/styles.css'], // delivered ahead of Animus's own CSS
    dependencies: ['react-datepicker'], // CSS these packages' modules import
    optOut: [], // exact files whose own rules stay unlayered
  },
})(nextConfig);
```

它需要网络包装: `next dev` 财务报告和审定财务报表 `next build` 在接下来的15, `--webpack` 打开 下十六会. Turbopack 在样式表上不运行加载器 导入样式表, 这样 `quarantine` 设置任何涡轮包运行失败的配置加载, 任意 页:1 `turbopack` 选项 。 下一个标记通过设置运行的涡轮包 `TURBOPACK`,所以Animus拒绝当该变量被设定时,甚至是空的. 反调:a `TURBOPACK` 从环境中继承的 网络包构建 下15,响亮,如此清晰的 CI 的 stale 值.

厂商样式表 层门完成不保存在 Webpack 的持久性中 缓存,所以一个温暖的重建再次完成它们:大约每200个供应商118毫秒 在合成测量中.

`sheets` 到达Animus自己的风格表的头, 在每一页. `!important` 宣言和动画仍然获胜,并被报道。 应用 CSS 保持自身规则的不高; 在导入供应商文件时, 该文件 是分层的。 CSS模块被单独搁置. 遥控器 `@import` 在供应商中 样式表是一个错误: 本地销售工作表, 或者如果 不分层是可以接受的.

## 外观花纹( 无 FOUC 颜色模式)

可选的 以零运行时间恢复第一次油漆前的持久颜色模式 - 生成的无依赖性内线片段,其CSP散列计算在 从生成的确切字节建立时间.

插件刻意注入一无所有: CSP 非ce 需要请求时间控制 捆绑者没有,所以 **应用程序** 将文物放入地. 生成 它在只使用服务器的模块中,并且作为第一个孩子插入 `<head>`。 。 。 .

**应用路由器 :**

```tsx
// appearance-bootstrap.ts — server-only; never import from a client component
import { createAppearanceBootstrap } from '@animus-ui/system/bootstrap';

import { theme } from './src/ds';

export const appearanceBootstrap = createAppearanceBootstrap(theme);
```

```tsx
// app/layout.tsx
import { appearanceBootstrap } from '../appearance-bootstrap';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script
          data-animus-bootstrap=""
          dangerouslySetInnerHTML={{ __html: appearanceBootstrap.code }}
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

**页面路由器 :** 同样的文物,作为第一个孩子 `<Head>` 内 `pages/_document.tsx`,与 `suppressHydrationWarning` 打开 `<Html>`。 。 。 .

两种规则都一样:

-   `suppressHydrationWarning` 需要的是根部元素,而不是化妆品 - 片段合法变异 `data-color-mode` 介于SSR和水分之间.
-   提供CSP,授权从文物本身获取脚本: `script-src '<artifact.cspHash>'` (单引出,出自建设时. ) 从未手抄; 重新命名的模式会改变散列) 或按要求复制的无序 您添加到脚本标签中。 完整的CSP脚枪记录在 [`@animus-ui/vite-plugin` 读取](https://github.com/codecaaron/animus/tree/main/packages/vite-plugin#content-security-policy)。 。 。 .

## 字体预装

声明字体面相 `preload: true` 可以在 样式表 `@font-face` 适用。 插件没有注入到 文档,所以要将它交付的组件。 当 没有正面预装.

`fontPreloads` 内 `withAnimus`选项选择预装的面孔 国家 `preload` 旗下,对于一个只使一些 系统面孔:一个姓氏选择家庭的每个面孔 `{ family, weight?, style? }` 上面写着: `weight` 和它的风格是 `style` (单位:千美元)`'normal'` 页:1 一个入口 `fetchpriority` (单位:千美元)`'high'`, (中文(简体) ), `'low'` 或者说 `'auto'`达到预装值 面对它选择. `[]` 预装无。 没有面相匹配的报表条目 `animus.style.font-preload-unmatched`· ; 一个畸形的,例如重量范围, `animus.style.font-preload-invalid`。 。 。 .

**应用路由器 :** 提交 `AnimusFontPreloads` 在根的布局中。 反应起搏器 每个预装入 `<head>` 前面的样式表, 和脱去它由赫雷夫, 反对 `next/font` 我也一样.

```tsx
// app/layout.tsx
import { AnimusFontPreloads } from '@animus-ui/next-plugin/font-preloads';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AnimusFontPreloads />
        {children}
      </body>
    </html>
  );
}
```

**页面路由器 :** 提交 `AnimusFontPreloadLinks` 内部 `<Head>` 内 `pages/_document.tsx`。它使简单 `<link>` 标记,任何反应 版本实现 .

样式表的 URL 名称 `url()` 负载( 散列) `/_next/static/media/…` 文件,在网络包装和涡轮包装下,在构建和 )),因此浏览器会获取文件一次. `withAnimus` 添加这个 软件包到 `transpilePackages`,然后将组件捆绑并解析 它读取的模块。 没有什么东西能检测到一个布局 永远不会使 组件:在样式表应用时,将面相加载,如同没有 `preload`。 。 。 .

预装与关键 CSS 和 JavaScript 相竞争,所以 预装 WOFF2 并只装入第一个屏幕所需的面孔: 一个大型的 TrueType 文件可以在缓慢的链接上将第一次油漆延迟数秒。 预装文件 不是WOFF2或WOFF,或是一个 `asset()` 超过150 KB的文档,报告 `animus.style.font-face-preload-costly`。 。 。 .

## 磁共振

Animus 读每个 `.mdx` \* 作为其JSX:进口、出口、, 标记、道具和 `{expressions}`它不需要MDX编译器。 组件标记 名称,或您的供应商之一的下图`# x` 你的头,数 现予公布。 马克倒数和代码例子 使什么也没有.

MDX 生成组件; 它宣布没有样式 。 Animus报告任何参考资料 到它的建筑者在一个 `.mdx` 文件为 `SOURCE_MDX_STYLE_DECLARATION`,则a 严格建设失败。 包括从 `@animus-ui/system`, (中文(简体) ), 以及任何以建造方法命名的成员(`styles`, (中文(简体) ), `variant`, (中文(简体) ), `compound`, (中文(简体) ), `states`, (中文(简体) ), `system`, (中文(简体) ), `props`, (中文(简体) ), `extend`, (中文(简体) ), `asElement`, (中文(简体) ), `asComponent`, (中文(简体) ), `asClass`),读取,调用或分解. 这么说吧 `{Box.styles}` 也报告。 宣布组件为 `.ts` 或者说 `.tsx` 文档并导入它们.

## 它会做什么

-   变换 `@animus-ui/system` 构建链入静态 CSS( webpack 加载器或涡轮加载器规则)
-   将提取的CSS作为单独资产 `@layer` 命令
-   使用闪电 CSS 处理已发射的工作表后- 为您自动前置 `targets` (浏览器列表查询;默认项目配置),生产中精密化(`minify` (原始内容存档于2017-03-25). overse. 没有目标 `:dir()` 放下来 `:lang()`,该元素仅设定 `dir` 不相配;建筑将发出警告 `keepDirSelector: true` 保持写法,添加 `dir-selector` 改为 `experimental.lightningCssFeatures.exclude` 所以Next自己的闪电CSS通行证也保留下来了
-   与 App 路由器和页面路由器同时工作
-   支持 RSC — 没有运行时样式注入意味着服务器组件在框外工作

## 许可证

麻省理工学院

## 常见问题

### @animus-ui/next-plugin 是什么？

Animus 静态 CSS 提取 Next\.js \(webpack\)

### 如何安装 @animus-ui/next-plugin？

在项目目录运行 npm install @animus-ui/next-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=15 \<17）、webpack（\>=5 \<6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @animus-ui/next-plugin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @animus-ui/next-plugin 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @animus-ui/next-plugin 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @animus-ui/next-plugin 可以商用吗？

@animus-ui/next-plugin 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @animus-ui/next-plugin 的下载量有多少？

根据 npm 官方下载统计，@animus-ui/next-plugin 在 2026/10/06 – 2026/11/04 这 30 天内被下载 6,619 次，日均约 221 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @animus-ui/next-plugin 还在维护吗？

最新版本 0\.1\.87 发布于 2026/10/24（14 天前）；至今共发布 101 个版本，其中过去 12 个月发布了 101 个；首次发布于 2026/04/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。