# @equinor/fusion-framework-vite-plugin-raw-imports 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-vite-plugin-raw-imports/

版本：2\.0\.6
npm 元数据更新时间：2026-11-12T09:55:00.398Z
中文译文更新时间：2026-11-13T20:32:55.261Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-vite-plugin-raw-imports
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-vite-plugin-raw-imports/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

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

- 包体积（解压后）：155 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-12-04T12:13:49.426Z
- 最新版本发布：2026-11-12T09:54:59.931Z
- 近 30 天下载量：7894（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

处理 ?raw 导入的 Vite 插件

## 安装

```sh
npm install @equinor/fusion-framework-vite-plugin-raw-imports
```

也可以使用：`pnpm add @equinor/fusion-framework-vite-plugin-raw-imports`、`yarn add @equinor/fusion-framework-vite-plugin-raw-imports`、`bun add @equinor/fusion-framework-vite-plugin-raw-imports`

## README

# @ equinor/ inform-framework-vite-plugin-raw- 进口

将文本文件嵌入为内置字符串模块的 Vite 插件 `?raw` 进口.

需要可靠原始字符串导入时使用此插件 **Vite 库模式** (单位:千美元)`build.lib`)或当Vite内置时 `?raw` 处理者处理不当 深陷相对路径。 它自动包含在 `@equinor/fusion-framework-cli`。 。 。 .

> \[注\] 虚拟支持 `?raw` 原产地进口,但视其为静态资产. 此插件在构建时读取文件并直接内入内容 输入 JavaScript 捆绑,所以字符串可以在运行时使用,而不包含 单独的资产请求.

## 谁应该使用这个

-   **Fusion app开发者** —— 插件在构建时已经激活 `@equinor/fusion-framework-cli`不需要设置.
-   **图书馆作者** 与 `vite build --lib` 将标记、文本或模板文件导入为字符串.
-   **谁都行** 从 Vite 本地打出 404 或错误的路径 `?raw` 与深度的相对进口.

## 快速启动

### 自动( Fusion CLI)

如果你建造与 `@equinor/fusion-framework-cli`,插件为您注册。 只是导入 :

```typescript
import readme from '../../README.md?raw';
console.log(readme); // full file content as a string
```

### 手动安装

```bash
pnpm add -D @equinor/fusion-framework-vite-plugin-raw-imports
```

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { rawImportsPlugin } from '@equinor/fusion-framework-vite-plugin-raw-imports';

export default defineConfig({
  plugins: [rawImportsPlugin()],
});
```

## 关键概念

### 构建- 时间嵌入

该插件运行于Vite建造(和dev-server)转换管道期间. 当它遇到一个像 `'./notes.md?raw'`,则:

1.  确定文件路径相对于导入模块.
2.  从磁盘读取文件内容.
3.  返回虚拟模块 : `export default "<file content>"`。 。 。 .

结果是一个普通的JavaScript字符串——运行时没有资产请求.

### 扩展过滤

只默认 `.md` 文件被截取。 所有其他 `?raw` 进口(图像、遮蔽等)通过Vite的内置处理器,因此现有的进口继续运作.

### 执行阶段

插件注册到 `enforce: 'pre'`,意思是它解决进口 **在此之前** Vite的内部资产插件. 这避免了库模式下的冲突.

## 常见模式

### 在反应组件中显示下划线

```tsx
import readmeContent from '../../README.md?raw';
import '@equinor/fusion-wc-markdown/markdown-viewer';

export default function AboutPage() {
  return <fwc-markdown-viewer>{readmeContent}</fwc-markdown-viewer>;
}
```

### 处理其他文件扩展名

```typescript
import { rawImportsPlugin } from '@equinor/fusion-framework-vite-plugin-raw-imports';

export default defineConfig({
  plugins: [
    rawImportsPlugin({
      extensions: ['.md', '.txt', '.json'],
    }),
  ],
});
```

> \[注\] 扩展未列在 `extensions` 选项由 Vite 处理 内置 `?raw` 支持,因此图像和阴影导入仍然不受影响.

### 为 Raw 导入添加类型脚本声明

创建声明文件, 从而 TypeScript 识别 `?raw` 进口:

```typescript
// src/types/raw.d.ts
declare module '*.md?raw' {
  const content: string;
  export default content;
}
```

### 解析各种路径格式

```typescript
import a from './file.md?raw';            // same directory
import b from '../README.md?raw';         // parent directory
import c from '../../docs/guide.md?raw';  // deeply nested relative
import d from '/src/docs/guide.md?raw';   // absolute from project root
```

路径是相对于导入文件目录解决的.

## API 表面

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `rawImportsPlugin` | `(options?: RawImportsPluginOptions) => Plugin` | 创建 Vite 插件实例的工厂 . |
| `default` | 与 `rawImportsPlugin` | 为方便的一线程使用默认导出 . |
| `RawImportsPluginOptions` | `interface` | 工厂接受的配置对象 . |

### `rawImportsPlugin(options?)`

创建截取 Vite 插件 `?raw` 导入已配置的文件扩展名并将其内容作为内置字符串模块.

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `options` | `RawImportsPluginOptions` | `undefined` | 可选配置对象 . |
| `options.extensions` | `string[]` | `['.md']` | 要截取的文件扩展名 。 每个条目必须包括主点. |

**回返情况:** `Plugin` ——一个 Vite 插件 `resolveId` 财务报告和审定财务报表 `load` 钩子.

**掷出 :** `Error` 当匹配的文件无法从磁盘读取时。 错误消息包括已解析的路径和基本的OS错误:

```
Failed to read file: /absolute/path/to/file.md. ENOENT: no such file or directory
```

## 何时使用此插件对 Vite 的内置 `?raw`

| 假设 | 建议 |
| --- | --- |
| 标准应用程序构建, 内部文件 `src/` | 维特的内置 `?raw` 通常已经足够. |
| 图书馆的构建 `build.lib` | 使用此插件——Vite的本地处理器可能不一致. |
| 深筑相对道路(`../../`(中文(简体) ) | 使用这个插件——它能更可靠地解决相对路径. |
| 二进制文件(图像、字体) | 执行 **没有** 使用此插件 – 它只读作 UTF-8 文本 . |

## 限制和限制

-   **只有文本文件** —— 二进制内容将被损坏, 因为插件读取时 `utf-8` 编码.
-   **仅构建时间** ——在构建时获取文件内容;运行时文件更改不反映.
-   **套装大小** ——大型文件被嵌入到JavaScript捆绑中,这影响了捆绑大小.

## 相关软件包

-   `@equinor/fusion-framework-cli` ——默认包含此插件的 CLI 用于所有 Vite 构建 .
-   `@equinor/fusion-imports` ——以建设为主的建筑具有类似的生入功能.

## 常见问题

### @equinor/fusion-framework-vite-plugin-raw-imports 是什么？

处理 ?raw 导入的 Vite 插件

### 如何安装 @equinor/fusion-framework-vite-plugin-raw-imports？

在项目目录运行 npm install @equinor/fusion-framework-vite-plugin-raw-imports，或使用 pnpm add / yarn add / bun add。

### @equinor/fusion-framework-vite-plugin-raw-imports 支持 TypeScript 吗？

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

### @equinor/fusion-framework-vite-plugin-raw-imports 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/fusion-framework-vite-plugin-raw-imports 可以商用吗？

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

### @equinor/fusion-framework-vite-plugin-raw-imports 的下载量有多少？

根据 npm 官方下载统计，@equinor/fusion-framework-vite-plugin-raw-imports 在 2026/10/14 – 2026/11/12 这 30 天内被下载 7,894 次，日均约 263 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/fusion-framework-vite-plugin-raw-imports 还在维护吗？

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