# @blakearoberts/visage 中文文档

规范地址：https://npmcn.com/package/%40blakearoberts/visage/

版本：0\.0\.6
npm 元数据更新时间：2026-11-14T16:10:40.868Z
中文译文更新时间：2026-11-14T16:12:10.808Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：116 kB，34 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：vite ^8\.0\.0
- 首次发布：2026-05-11T02:13:34.187Z
- 最新版本发布：2026-11-14T16:10:40.501Z
- 近 30 天下载量：4101（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：158（近 12 个月 158 个）

## 中文简介

HMR 和 OIDC 会话 cookie 生命周期语义用于本地开发的 Vite 插件 .

## 安装

```sh
npm install @blakearoberts/visage
```

也可以使用：`pnpm add @blakearoberts/visage`、`yarn add @blakearoberts/visage`、`bun add @blakearoberts/visage`

## README

# 签证

签证`/vit·ɛdʒ/`)是HMR和OIDC用于本地开发的Vite插件 会话饼干生命周期语义.

## 开始

从 npm 安装 Visage :

```console
npm install @blakearoberts/visage@next
```

将插件添加到 `vite.config.ts`数字 :

```ts
import { defineConfig } from 'vite';
import visage from '@blakearoberts/visage';

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

正常启动 Vite :

```console
vite
```

默认情况下,您可以在 `https://localhost:9001`你会是 重新定向到 Dex 注册 。 默认用户名和密码是 `user@example.com` 财务报告和审定财务报表 `pass`。 。 。 .

## 为什么是Visage

Visage是一个本地开发工具,用于运行在网络应用程序后面 认证保护的边缘, 浏览器会话由安全的 cookie 代表 由 OIDC 符号支持.

Visage缩小了本地开发、自动化测试和 将类似生产的会议周期语义带入当地 Vite 在不放弃HMR的情况下发展。 这样就可以在安全部门改革上提法 身份注入、会话超时恢复、锁屏和认证 API电话.

Visage也可以使用主机IDP,所以本地前端代码可以调用主机后端 具有真实资格的API. 这样可以避免只使用前端的 Auth 模拟或只使用后端 本地绕道:代码可以被写作制作,仍然在当地工作.

## 系统块图

```mermaid
flowchart LR
  browser([Browser])
  vite([Vite])
  upstreams([Upstreams])

  subgraph docker[Docker]
    nginx[NGINX]
    services([Services])
    Oauth2-Proxy
    idp(["IdP (Dex)"])

    nginx -.-> idp
    nginx -.-> Oauth2-Proxy -.-> idp
    nginx --> services
  end

  browser --> nginx
  nginx --> vite
  nginx ---> upstreams
```

## 配置

Visage 通过配置 `visage(options?)` 内 `vite.config.ts`。 。 。 .

高层 `host` 财务报告和审定财务报表 `port` 配置本地 Visge 源代码 浏览器访问 :

```ts
visage({ host: 'localhost', port: 9001 });
```

### 服务

服务是多克编译服务,由Vite dev-server生命周期管理. 服务在应用程序主机上自动创建上游位置 `/{name}` visage 在向服务主机代理请求之前删除它.

```ts
visage({
  services: { whoami: { image: 'traefik/whoami' } },
});
```

#### 服务网络

每个服务都加入自己的私人多克网络. NGINX 加入个人 上游服务网络。 允许直接服务 连接, 在每个服务中添加相同的网络名称 `networks` 列表中选择一个选项.

```ts
visage({
  services: {
    api: { image: 'example/api' },
    res: { image: 'mysql', upstream: false, networks: ['api'] },
  },
});
```

### 远程

远程是上游的,没有Visage管理的多克集装箱流程。 远程 在后面的应用程序主机上自动创建上游位置 `/{name}` visage 在向上游主机代理请求之前删除它.

```ts
visage({
  remotes: {
    api: { host: 'api.remote.test' },
  },
});
```

服务和远程地点不默认转发无记名符号. 设定 `auth.forward` 改为 `true` 向上游转发默认的无记名符号 类型:远程接收 OAuth 访问符,而服务接收 OIDC ID 符号 .

主机后端的验证持卡人认证的 API 一般应当接收 只要是给API的发行人、观众和 瞄准镜。 使用 `'access'` 或者说 `'id'` 当你需要强迫一种特定的标志.

```ts
visage({
  remotes: {
    api: {
      host: 'api.remote.test',
      auth: { forward: true },
    },
  },
});
```

OAuth2 证书 代理服务器也可以返回 `X-Auth-Request-Groups` 财务报告和审定财务报表 `X-Auth-Request-Preferred-Username`但Visage不捕捉或转发它们 自动。 根据需要获取和转发可选身份值:

```ts
visage({
  remotes: {
    api: {
      directives: {
        auth_request_set: [
          '$auth_groups $upstream_http_x_auth_request_groups',
          '$auth_preferred_username $upstream_http_x_auth_request_preferred_username',
        ],
      },
      headers: {
        'X-Auth-Request-Groups': '$auth_groups',
        'X-Auth-Request-Preferred-Username': '$auth_preferred_username',
      },
    },
  },
});
```

经认证的地点还默认会获得CSRF的检查. 设定 `csrf: false` 何时 上游故意处理跨站点浏览器请求本身。 见 [CSRF 政策](https://npmcn.com/package/docs/csrf-policy.md)。 。 。 .

### 外部 IdPs 软件

默认的 IdP, Dex 可以替换为外部的 OIDC 提供者 :

```ts
visage({
  idp: { issuer: 'https://idp.example.test/oauth2/default' },
});
```

配置 `authorization`, (中文(简体) ), `token`,或 `jwks` 仅在提供者端点时 必须明确表示,而不是从发行人那里发现。 配置 `end_session_endpoint` 当提供者支持 OIDC 结束会话重定向时.

身份提供者的主要认可和配置 OAuth2 代理接受任何由该发行商声称的非空邮件. 管理 德克丝, `idp.users` 是完整的合格用户列表。 与外部IPP,它的 客户登记和申请分配政策必须确保每个身份 为 Visage 客户端获取 OIDC 响应的 本地应用程序; Visage 不应用额外的电子邮件域允许列表 .

### 遥测

设定 `telemetry` 以便收集、编辑和导出遥测信号 通过OTLP/gRPC.

-   当启用时, Visage 配置 :
    
    -   (一) NGINX出口进入收集器;
    -   OAuth2 代理Prometheus 度量衡听取器被收集器刮去;
    -   向收集者发送 stdout/stder的服务容器;
    -   接收经认证的OTLP/HTTP信号的收集器 `/t/`。 。 。 .
-   收集器输出OTLP到 `host.docker.internal:4317` 默认 [遥测示例](https://npmcn.com/package/examples/telemetry) 演示如何配置 Grafana作为Visage公司管理着接收和观看遥测的服务.
    

见 [`VisageOptions`](https://npmcn.com/package/%40blakearoberts/visage/src/types.ts) 整个选项表面.

## 所需工具

-   [夹克](https://docs.docker.com/get-started/get-docker/) 随作曲 v2 通过下列方式提供支助: `docker compose`。 。 。 .
-   [`mkcert`](https://github.com/FiloSottile/mkcert#installation) 安装于 `PATH`,或配置为 `VISAGE_MKCERT=/path/to/mkcert`。 。 。 .

## 管理多克图像

Visage根据配置需要拉出这些:

| 服务 | 图像 |
| --- | --- |
| [纳吉林克斯](https://nginx.org/) | [`visage-nginx`](https://github.com/blakearoberts/visage/pkgs/container/visage-nginx) |
| [OAuth2 代理服务器](https://oauth2-proxy.github.io/oauth2-proxy/) | [`quay.io/oauth2-proxy/oauth2-proxy`](https://quay.io/repository/oauth2-proxy/oauth2-proxy) |
| [德克斯语Name](https://dexidp.io/) | [`ghcr.io/dexidp/dex`](https://github.com/dexidp/dex/pkgs/container/dex) |
| [打开数位收集器](https://opentelemetry.io/docs/collector/) | [`otel/opentelemetry-collector-contrib`](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) |
| [小猫](https://www.dest-unreach.org/socat/) | [`alpine/socat`](https://hub.docker.com/r/alpine/socat) |

Visage默认使用的图像标签由显示文件定义, [docker-compaces.images.yml 页面存档备份,存于互联网档案馆](https://npmcn.com/package/%40blakearoberts/visage/docker-compose.images.yml)。 。 。 .

## 安全说明

Visage是地方开发工具。 它启动了本地认证基础设施, 终止本地 HTTPS, 并将认证身份或符号材料转发给 上游配置 .

请通过 GitHub 私人弱点报告疑似弱点 报告说明 [安全政策](https://npmcn.com/package/SECURITY.md)。 。 。 .

不将管理中的 Dex 和 OAuth2 代理默认作为生产认证处理 基础设施.

Visage的CSRF政策是CSRF对饼干后置位置的边缘控制. 普通同源SPA变异不需要CSRF令牌 根据这项政策。 当一个位置禁用时, App 级的符号可能仍然有用 边框策略,有意接受跨站点浏览器请求,或需要 符号编码额外的授权语义 。 萨赫勒农药委员会, `frame-ancestors`, (中文(简体) ), 其他点击劫持控制仍然是应用政策.

## 解决问题

-   如果启动立即失败, 请确认 Docker 正在运行 `docker compose` 工作时.
-   如果 NGINX 无法启动, 请检查是否配置 `port` 已经使用.
-   如果主机名无法解决, Visage 可能需要权限更新 `/etc/hosts`。 。 。 .

## 常见问题

### @blakearoberts/visage 是什么？

HMR 和 OIDC 会话 cookie 生命周期语义用于本地开发的 Vite 插件 \.

### 如何安装 @blakearoberts/visage？

在项目目录运行 npm install @blakearoberts/visage，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blakearoberts/visage 支持 TypeScript 吗？

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

### @blakearoberts/visage 支持 ESM 还是 CommonJS？

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

### @blakearoberts/visage 需要什么版本的 Node\.js？

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

### @blakearoberts/visage 可以商用吗？

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

### @blakearoberts/visage 的下载量有多少？

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

### @blakearoberts/visage 还在维护吗？

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