# @asd14/vblocks 中文文档

规范地址：https://npmcn.com/package/%40asd14/vblocks/

版本：6\.2\.0
npm 元数据更新时间：2026-10-29T08:14:56.363Z
中文译文更新时间：2026-11-08T03:17:20.610Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40asd14/vblocks
原文对照：https://npmcn.com/package/%40asd14/vblocks/?lang=original
项目主页：https://github.com/asd-xiv/vblocks#readme
源码仓库：https://github.com/asd-xiv/vblocks

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

- 包体积（解压后）：125 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.3 \|\| ^24\.15\.0 \|\| \>=26\.0
- 运行依赖：20 个
- peer 依赖：react ^18 \|\| ^19，react-dom ^18 \|\| ^19
- 首次发布：2025-09-18T09:06:01.774Z
- 最新版本发布：2026-10-29T08:14:55.881Z
- 近 30 天下载量：1920（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 13 个）

## 中文简介

零配置 React 构建, 作为静态站点或单一的 HTML 文件

## 安装

```sh
npm install @asd14/vblocks
```

也可以使用：`pnpm add @asd14/vblocks`、`yarn add @asd14/vblocks`、`bun add @asd14/vblocks`

## README

[![Release](https://github.com/asd-xiv/vblocks/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/asd-xiv/vblocks/actions/workflows/main.yml) [![npm version](https://img.shields.io/npm/v/@asd14/vblocks.svg)](https://www.npmjs.com/package/@asd14/vblocks)

# @asd14/vblocks (英语)

> 零配置 React 构建, 作为静态站点或单一的 HTML 文件

**零配置**  
仅需要 `src/index.tsx` 财务报告和审定财务报表 `src/index.html`

**🔋 最大支持**  
SWC, PostCSS, CSS 模块, MDX, 反应刷新, 多腾夫

**几个应用,一个安装**  
Apps 共享一个 `package.json` 财务报告和审定财务报表 `node_modules/`。一个新的应用程序重新使用 已安装的软件包

**为AI代理优化**  
代理上下文只持有应用程序 : 没有 Webpack, PostCSS 或 TypeScript 配置 写入、读取或修正

> \[大  
> VBlocks 需要节点 `^22.22.3`, (中文(简体) ), `^24.15.0` 或者说 `>=26.0`。 。 。 .

## 目录

-   [快速启动](https://npmcn.com/package/%40asd14/vblocks/#readme-quick-start)
    -   [一个项目中的几个应用程序](https://npmcn.com/package/%40asd14/vblocks/#readme-several-apps-in-one-project)
-   [词汇](https://npmcn.com/package/%40asd14/vblocks/#readme-vocabulary)
-   [怎么样](https://npmcn.com/package/%40asd14/vblocks/#readme-how-to)
    -   [使用环境变量](https://npmcn.com/package/%40asd14/vblocks/#readme-use-environment-variables)
    -   [停止使用 `../../../` 到处都是](https://npmcn.com/package/%40asd14/vblocks/#readme-stop-using--everywhere)
    -   [使用 CSS 模块](https://npmcn.com/package/%40asd14/vblocks/#readme-use-css-modules)
    -   [替换默认配置](https://npmcn.com/package/%40asd14/vblocks/#readme-replace-a-default-config)
    -   [有尾风的样式](https://npmcn.com/package/%40asd14/vblocks/#readme-style-with-tailwind)
    -   [在现有工程中添加 VBlocks](https://npmcn.com/package/%40asd14/vblocks/#readme-add-vblocks-to-an-existing-project)
-   [参考资料](https://npmcn.com/package/%40asd14/vblocks/#readme-references)
    -   [图标](https://npmcn.com/package/%40asd14/vblocks/#readme-commands)
        -   [`vblocks init`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-init)
        -   [`vblocks serve`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-serve)
        -   [`vblocks build`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-build)
        -   [`vblocks eject`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-eject)
    -   [模板](https://npmcn.com/package/%40asd14/vblocks/#readme-templates)
        -   [`plain`](https://npmcn.com/package/%40asd14/vblocks/#readme-plain)
        -   [`xyflow`](https://npmcn.com/package/%40asd14/vblocks/#readme-xyflow)
        -   [`xyflow-tabs`](https://npmcn.com/package/%40asd14/vblocks/#readme-xyflow-tabs)
-   [许可证](https://npmcn.com/package/%40asd14/vblocks/#readme-license)

## 快速启动

1.  **脚手架最小反应项目**
    
    ```sh
    npx @asd14/vblocks init my-vblocks-app
    cd my-vblocks-app
    npm install
    ```
    
    ```text
    my-vblocks-app/
     ├─ src/
     │    ├─ index.tsx
     │    ├─ index.html
     │    └─ index.css
     ├─ .gitignore
     ├─ tsconfig.json
     └─ package.json      # react, react-dom and the vblocks scripts
    ```
    
2.  **启动开发服务器**
    
    ```sh
    npx vblocks serve
    ```
    
3.  **构建**
    
    ```sh
    npx vblocks build               # production bundle in dist/
    npx vblocks build --single-file # one dist/index.html, every asset inlined
    ```
    

### 一个项目中的几个应用程序

多个应用程序,如演示或MVP草图,可以共享一个 `package.json` 和一个 `node_modules/`数字 :

1.  **增加水管**
    
    ```sh
    npx @asd14/vblocks init sketches --only plumbing
    ```
    
    ```text
    sketches/
     ├─ .gitignore
     └─ package.json
    ```
    
2.  **添加应用程序**
    
    ```sh
    npx @asd14/vblocks init sketches/flow-diagram --template xyflow --only app
    cd sketches
    npm install
    ```
    
    ```diff
     sketches/
    + ├─ flow-diagram/
    + │   ├─ src/          # the files of the xyflow template
    + │   ├─ postcss.config.js
    + │   └─ tsconfig.json
      ├─ .gitignore
    ! └─ package.json      # + @xyflow/react, tailwindcss, @tailwindcss/postcss, cssnano
    ```
    
3.  **启动一个应用程序的开发服务器**
    
    ```sh
    npx vblocks serve --prefix flow-diagram
    ```
    

## 词汇

| 任期 | 手段 |
| :-- | :-- |
| **接线** | 项目文件 `init` 写道: `package.json`, (中文(简体) ), `.gitignore` |
| **项目文件夹** | 文件夹与 `package.json` |
| **App 文件夹** | 文件夹与 `src/index.tsx` 财务报告和审定财务报表 `src/index.html` |
| **套装** | 文件 `build` 写到 `dist/` |

## 怎么样

### 使用环境变量

1.  **添加一个 `.env` 文件到您的应用程序文件夹**
    
    ```env
    API_URL=https://api.example.com
    ```
    
2.  **读取代码中的变量**
    
    ```tsx
    const apiUrl = process.env["API_URL"]
    ```
    

网页包替换每个 `process.env["NAME"]` 值为 `NAME`,以及 `undefined` 何时 `.env` 不设置它。 Webpack 树叶出捆绑 变量代码不读取.

> \[尖叫声\]  
> 从不泄露秘密,例如API密钥,通过 `process.env`任何装载者 页面可以读取.

> \[注\]  
> 这个 [客户类型](https://npmcn.com/package/%40asd14/vblocks/types/client.d.ts) 声明 `process.env` 没有别的了 从节点, 因为Webpack 取代了其他的.

### 停止使用 `../../../` 到处都是

VBlocks 解析 `@self` 页:1 `src/` 您的应用程序文件夹 :

```tsx
// Instead of: import { Component } from "../../../components"
import { Component } from "@self/components"
```

> \[注\]  
> VBlocks用 SWC 编译类型脚本,不进行打字检查. 运行 `tsc` 你自己来  `tsconfig.json` 需要和 Webpack 相同的别名.  
> 这个 `tsconfig.json` 那个 [`vblocks init`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-init) 已写 这个 否则,添加:
> 
> ```diff
>  {
>    "compilerOptions": {
> +    "paths": { "@self/*": ["./src/*"] }
>    }
>  }
> ```

### 使用 CSS 模块

1.  **文件名称 `*.module.css`**
    
    ```css
    /* src/button.module.css */
    .primary-button {
      color: tomato;
    }
    ```
    
2.  **作为对象导入**
    
    ```tsx
    /* src/button.tsx */
    import styles from "./button.module.css"
    
    export const Button = () => <button className={styles.primaryButton} />
    ```
    

-   **骆驼Case 键** - 说吧 `.primary-button` 变成 `styles.primaryButton`
-   **类名** - 一个赤裸的大麻花 `production` 模式, `[local]__[hash]` 内 `development` 模式

> \[注\]  
> 这个 [客户类型](https://npmcn.com/package/%40asd14/vblocks/types/client.d.ts) 声明 `.css`,图像和字体导入.

### 替换默认配置

您的应用程序文件夹中的每个配置都会替换同名的默认值 :

-   `webpack.config.js`
-   `postcss.config.js`
    -   `postcss-preset-env`编织出巢穴, `oklch()` 财务报告和审定财务报表 `color-mix()` 用于旧浏览器并添加销售商前缀
    -   `cssnano` 内 `production`
-   `.swcrc`
    -   浏览器目标 `> 0.25%, not dead`

1.  **[弹出](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-eject) 默认位于您的应用程序文件夹中**
    
    ```sh
    cd flow-diagram
    npx vblocks eject swc > .swcrc
    ```
    
2.  **更新弹出的文件**
    

> \[注\]  
> VBlocks 不将您的配置与默认合并, 除了两个例外 :
> 
> -   `.swcrc -> env.targets`: VBlocks 在缺少您的默认值时添加默认值
> -   `.swcrc -> jsc.transform.react.refresh`: VBlocks 添加反应刷新 当 `serve` 运行在 `development` 模式

### 有尾风的样式

VBlocks不包括"泰尔风". 通过一个加法 `postcss.config.js` 在你身边 应用程序文件夹 :

> \[注\]  
> 这个 `xyflow` 财务报告和审定财务报表 `xyflow-tabs` 模板 [`vblocks init`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-init) 有这个设置.

1.  **安装 Tailwind、 PostCSS 和 cssnano 的 Tailwind 插件, 其名称为 已弹出配置导入**
    
    ```sh
    npm install --save-dev tailwindcss @tailwindcss/postcss cssnano
    ```
    
2.  **弹出默认 PostCSS 配置到您的应用文件夹**
    
    ```sh
    npx vblocks eject postcss > postcss.config.js
    ```
    
3.  **替换 `postcss-preset-env` 带有 Tailwind 插件**
    
    ```diff
    +import tailwindcss from "@tailwindcss/postcss"
     import cssnano from "cssnano"
    -import postcssPresetEnv from "postcss-preset-env"
    
     export default ({ mode }) => ({
       plugins: [
    -    postcssPresetEnv({ stage: 2 }),
    +    tailwindcss({ optimize: mode === "production" }),
         ...(mode === "production" ? [cssnano({ preset: "default" })] : []),
       ],
     })
    ```
    

> \[大  
> 尾风 4 [编译并添加销售商前缀](https://tailwindcss.com/docs/compatibility) 自己来 两个插件, `postcss-preset-env` 重写 Tailwind的 `@layer` 规则进入 `:not(#\#)` 选择者。 CSS文件增长.

4.  **添加尾风导入到 `src/index.css`**
    
    ```css
    @import "tailwindcss" source(".");
    ```
    
    `source(".")` 将 Tailwind 的类扫描限制在 CSS 文件的文件夹中, `src/`。 。 。 .
    

> \[注\]  
> 无 `source(".")`,尾风扫描当前文件夹。 与 [`--prefix`](https://npmcn.com/package/%40asd14/vblocks/#readme-vblocks-build),您从工程文件夹中运行 VBlocks,该文件夹 持有每个应用程序。 每个应用程序的CSS,然后也获得其他应用程序的类.

### 在现有工程中添加 VBlocks

1.  **安装 VBlocks**
    
    ```sh
    npm install --save-dev @asd14/vblocks    # needs react and react-dom ^18 or ^19
    ```
    
2.  **添加数据 [客户类型](https://npmcn.com/package/%40asd14/vblocks/types/client.d.ts) 编辑 [`@self`](https://npmcn.com/package/%40asd14/vblocks/#readme-stop-using--everywhere) 您的别名 `tsconfig.json`**
    
    ```diff
     {
       "compilerOptions": {
    +    "types": ["@asd14/vblocks/client"],
    +    "paths": { "@self/*": ["./src/*"] }
       }
     }
    ```
    
3.  **保证 `index.tsx` 财务报告和审定财务报表 `index.html` 包含 `src/`**
    

> \[注\]  
> VBlocks 构建 `dist/index.html` 从 `src/index.html` 并添加脚本和 样式表标签。 放下装入您的条目的标签, 如 Vite's `<script type="module" src="/src/main.tsx"></script>`。 。 。 .

4.  **启动开发服务器**
    
    ```sh
    npx vblocks serve
    ```
    

## 参考资料

### 图标

每个命令都会打印自己的帮助 `--help`,比如说. `npx vblocks serve --help`。 。 。 .

#### `vblocks init`

将模板的管道、应用或两者都写入 `<directory>`。 。 。 .

```text
vblocks init <directory>
  [--template <plain|xyflow|xyflow-tabs>]
  [--only <app|plumbing>]
```

-   `<directory>`
    -   要写入的文件夹 。 一定是不见了还是空的
-   `--template` (默认 : `plain`(中文(简体) )
    -   要写入的模板见 [模板](https://npmcn.com/package/%40asd14/vblocks/#readme-templates)
-   `--only` (默认:两者兼有)
    -   写入模板的一部份
    -   `plumbing`数字 : `package.json`, (中文(简体) ), `.gitignore`
    -   `app`数字 : `src/`, (中文(简体) ), `tsconfig.json` 和模板的配置. `init` 添加 模板对 `package.json` 会 议 日 程 和 议 程 [项目文件夹](https://npmcn.com/package/%40asd14/vblocks/#readme-vocabulary)时 `<directory>`没有 `package.json` 那边, `init` 失败

#### `vblocks serve`

启动开发服务器 .

-   运行于 `http://localhost:8080`,或下一个自由端口
-   听着 `localhost`,所以你网络上的另一个设备,例如电话,不能 打开页面
-   打开浏览器中的页面

```text
vblocks serve
  [--mode <development|production>]
  [--prefix <directory>]
  [--analyze]
  [--log-level <error|warn|info|verbose>]
  [-- <webpack option>...]
```

-   `--mode` (默认 : `development`(中文(简体) )
    -   Webpack 模式
    -   反应刷新仅在其中运行 `development`
-   `--prefix` (默认: 当前文件夹)
    -   这个 [应用程序文件夹](https://npmcn.com/package/%40asd14/vblocks/#readme-vocabulary),必须存在
-   `--analyze`
    -   在自由端口运行捆绑分析器
-   `--log-level` (默认 : `warn`(中文(简体) )
    -   Webpack 及其开发服务器打印多少
-   `-- <webpack option>...`
    -   任意 [`webpack serve`](https://webpack.js.org/api/cli/) 选项
    -   `serve` 每一个都转到 Webpack 不变
    -   举个例子. `-- --host 0.0.0.0`在网络上听

#### `vblocks build`

将应用程序建为捆绑在 `dist/` 应用程序文件夹.

默认, `build`数字 :

-   撰写 JS 和 CSS 的有内容隐藏名称的文件
-   写入 a `react` 块和 a `vendors` 其它依赖关系时的块 总计20个KB(10个KB)以上 `development`(中文(简体) )
-   内插 `jpg`, (中文(简体) ), `gif`, (中文(简体) ), `png` 财务报告和审定财务报表 `svg` 不超过 10 KB 的文件
-   写入更大的图像到 `dist/` 含有包含内容的名称
-   写作 `woff`, (中文(简体) ), `woff2`, (中文(简体) ), `ttf` 财务报告和审定财务报表 `eot` 文件为 `dist/fonts/`
-   副本 `src/public/favicon.svg` 财务报告和审定财务报表 `src/public/robots.txt` 您的应用程序,或 默认 VBlocks

```text
vblocks build
  [--mode <development|production>]
  [--prefix <directory>]
  [--single-file|--single]
  [--log-level <error|warn|info|verbose>]
  [-- <webpack option>...]
```

-   `--mode` (默认 : `production`(中文(简体) )
    -   Webpack 模式
    -   单位 `production`, (中文(简体) ), `build` 修改JS、HTML和默认的PostCSS 配置, CSS
-   `--prefix` (默认: 当前文件夹)
    -   这个 [应用程序文件夹](https://npmcn.com/package/%40asd14/vblocks/#readme-vocabulary),必须存在
-   `--single-file|--single`
    -   单独写一个 `dist/index.html`,每个资产
    -   浏览器从磁盘打开文件, 没有服务器和网络
    -   捆绑没有 `robots.txt`
    -   在 URL 散列中保留路径
        -   打开 `file://`, (中文(简体) ), `history.pushState` 向其它路径投掷
-   `--log-level` (默认 : `warn`(中文(简体) )
    -   网包印数
-   `-- <webpack option>...`
    -   任意 [`webpack build`](https://webpack.js.org/api/cli/) 选项
    -   `build` 每一个都转到 Webpack 不变
    -   举个例子. `-- --devtool source-map`,用于写入源地图

#### `vblocks eject`

打印默认配置到 stdout .

```text
vblocks eject <webpack|postcss|swc>
```

-   `<webpack|postcss|swc>`
    -   要打印的配置

在您的应用程序文件夹中运行并保存输出到 [替换默认](https://npmcn.com/package/%40asd14/vblocks/#readme-replace-a-default-config)数字 :

```sh
npx vblocks eject webpack > webpack.config.js
npx vblocks eject postcss > postcss.config.js
npx vblocks eject swc > .swcrc
```

一个被弹出配置从您的工程中加载其插件和加载器 。 安装它们 在项目文件夹中, eg. `postcss-preset-env` 财务报告和审定财务报表 `cssnano` 邮政编码 相会.

### 模板

所有模板脚手架 `src/index.html`, (中文(简体) ), `src/index.css` 财务报告和审定财务报表 `tsconfig.json`。 。 。 .

#### `plain`

"Hello World!" 进入 `src/index.tsx`。 。 。 .

-   不添加软件包

#### `xyflow`

一个图,和一个选定节点或边缘的细节面板.

-   添加数 `@xyflow/react`, (中文(简体) ), `tailwindcss`, (中文(简体) ), `@tailwindcss/postcss` 财务报告和审定财务报表 `cssnano` 改为 页:1 `package.json` 项目文件夹
-   写入 a `postcss.config.js` 配置尾风

```text
src/
├── index.tsx           # the layout: header, diagram, details panel, the selected id
├── diagram.tsx         # the nodes and edges, placed and sized in grid cells
├── details.tsx         # the panel for the selected node or edge
└── utils/grid.ts       # CELL_SIZE and toPixels
```

#### `xyflow-tabs`

每个图一个分页,每个分页都有自己的细节面板.

-   添加相同的软件包和 `postcss.config.js` 作为 `xyflow`

```text
src/
├── index.tsx              # the layout: header, tab bar, details panel, the selected id
├── pages/
│   ├── build/
│   │   ├── diagram.tsx    # the nodes and edges of one tab, in grid cells
│   │   └── details.tsx    # the panel for its selected node or edge
│   └── serve/             # the same two files
├── ui/zoom-level.tsx      # the zoom level, and a Reset to 100%
└── utils/grid.ts          # CELL_SIZE and toPixels
```

## 许可证

麻省理工学院

## 常见问题

### @asd14/vblocks 是什么？

零配置 React 构建, 作为静态站点或单一的 HTML 文件

### 如何安装 @asd14/vblocks？

在项目目录运行 npm install @asd14/vblocks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 \|\| ^19）、react-dom（^18 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 vblocks，可以用 npx vblocks 直接运行。

### @asd14/vblocks 支持 TypeScript 吗？

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

### @asd14/vblocks 支持 ESM 还是 CommonJS？

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

### @asd14/vblocks 需要什么版本的 Node\.js？

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

### @asd14/vblocks 可以商用吗？

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

### @asd14/vblocks 的下载量有多少？

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

### @asd14/vblocks 还在维护吗？

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