# @authhero/admin 中文文档

规范地址：https://npmcn.com/package/%40authhero/admin/

版本：0\.26\.5
npm 元数据更新时间：2026-11-05T14:45:54.566Z
中文译文更新时间：2026-11-07T06:04:55.189Z
软件包许可：AGPL-3\.0-only

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

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

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

- 包体积（解压后）：19.5 MB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：56 个
- 首次发布：2026-05-18T12:01:07.759Z
- 最新版本发布：2026-11-05T14:45:53.862Z
- 近 30 天下载量：2144（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 93 个）

## 中文简介

AuthHero admin UI – a Vite + React 19 SPA 用于管理租户,用户,应用程序,连接,角色,品牌等多个AuthHero部署.

## 安装

```sh
npm install @authhero/admin
```

也可以使用：`pnpm add @authhero/admin`、`yarn add @authhero/admin`、`bun add @authhero/admin`

## README

# @authhero/admin (英语)

AuthHero admin UI – a Vite + React 19 SPA 用于管理租户,用户,应用程序,连接,角色,品牌等多个AuthHero部署.

建造在 `ra-core` (无头半反应-admin)与 [阴影/ ui](https://ui.shadcn.com/) 和"尾风"v4.

## 快开始

```bash
# from the repo root
pnpm install
pnpm admin dev        # starts on http://localhost:5173

# or from this directory
pnpm dev
pnpm build            # production bundle in ./dist
pnpm type-check
pnpm test
```

## 配置

管理员从两个来源阅读其配置,按优先顺序排列:

1.  **运行时间配置** —— 说 `window.__AUTHHERO_ADMIN_CONFIG__` (捆绑负载前由主机页面注入). 当同一个静态建筑被服务到多个环境时是有用的.
2.  **构建时的嵌入区 vars** —— 说 `VITE_*` 变量在 `pnpm build` 时间.

两种路径共享相同的密钥,定义于 [`src/utils/runtimeConfig.ts`](https://npmcn.com/package/%40authhero/admin/src/utils/runtimeConfig.ts)。 。 。 .

### 设置

| 设置 | 新闻 var | 运行时键 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| Auth0 域名 | `VITE_AUTH0_DOMAIN` | `domain` | —— 说 | 租赁域 `@auth0/auth0-spa-js` 以登录管理员用户。 当未设定时,会提示用户在第一个负载上选择一个域. |
| Auth0 客户端标识 | `VITE_AUTH0_CLIENT_ID` | `clientId` | —— 说 | 管理员本人的 SPA 应用程序客户端ID . |
| 管理 API URL | `VITE_AUTH0_API_URL` | `apiUrl` | —— 说 | AuthHero 管理 API 的基础 URL(例如. `https://auth.example.com`) (中文(简体) ). |
| 观众 | `VITE_AUTH0_AUDIENCE` | `audience` | —— 说 | 管理API访问令牌的观众请求. |
| 基础路径 | `VITE_BASE_PATH` | `basePath` | `""` | 副路径管理员从(例如)服务. `/admin`) (中文(简体) ). 路由和OAuth召回 荣誉这一点. |
| 应用名称 | `VITE_APP_NAME` | `appName` | `"AuthHero Admin"` | 浏览器标签标题和上栏显示的文字标记(当没有设置标志时). |
| 标记 URL | `VITE_APP_LOGO_URL` | `logoUrl` | —— 说 | 图像在顶端的栏上显示,以代替文字标记 。 任何浏览器都可以显示(PNG,SVG,WebP). 建议高度:28px. |
| 费维孔 URL | `VITE_APP_FAVICON_URL` | `faviconUrl` | `./favicon.svg` | 超越了内在的法相. |

### 构建时嵌入示例

创建 `apps/admin/.env.local`数字 :

```bash
VITE_AUTH0_DOMAIN=auth.example.com
VITE_AUTH0_CLIENT_ID=your-spa-client-id
VITE_AUTH0_API_URL=https://auth.example.com
VITE_AUTH0_AUDIENCE=https://auth.example.com/api/v2/
VITE_BASE_PATH=/admin

# Whitelabel
VITE_APP_NAME="Acme Identity Console"
VITE_APP_LOGO_URL=https://cdn.example.com/acme-logo.svg
VITE_APP_FAVICON_URL=https://cdn.example.com/acme-favicon.svg
```

### 运行时配置示例

在捆绑之前插入到互换设置而不重建 :

```html
<script>
  window.__AUTHHERO_ADMIN_CONFIG__ = {
    domain: "auth.example.com",
    clientId: "your-spa-client-id",
    apiUrl: "https://auth.example.com",
    audience: "https://auth.example.com/api/v2/",
    basePath: "/admin",
    appName: "Acme Identity Console",
    logoUrl: "https://cdn.example.com/acme-logo.svg",
    faviconUrl: "https://cdn.example.com/acme-favicon.svg",
  };
</script>
<script type="module" src="/admin/assets/index-<hash>.js"></script>
```

捆绑条目文件名由Vite在构建时间(例如. `index-Ab12Cd.js`),因此替换您构建输出中的真实文件名——或使用 `window.__AUTHHERO_ADMIN_CONFIG__.basePath` 从配置的基础路径构造它.

如果两者都不提供 `domain`中,管理员在第一个负载上显示一个域拾取器,并将选择存储在通过 [`src/utils/domainUtils.ts`](https://npmcn.com/package/%40authhero/admin/src/utils/domainUtils.ts)。 。 。 .

## 白标签

三个品牌设置(`appName`, (中文(简体) ), `logoUrl`, (中文(简体) ), `faviconUrl`)在三个地方读取:

-   `document.title` 与法网 `<link>` 被设定为启动 `applyBranding()` 内 [`src/utils/runtimeConfig.ts`](https://npmcn.com/package/%40authhero/admin/src/utils/runtimeConfig.ts)。 。 。 .
-   上面的条子 [`src/components/admin/layout.tsx`](https://npmcn.com/package/%40authhero/admin/src/components/admin/layout.tsx) 调制 `logoUrl` 作为 `<img>` 设定时,否则 `appName` word-mark (以两字母首字母为窄宽格字母).

替换默认标记, 设置 `VITE_APP_FAVICON_URL` 到您自己的资产; 捆绑的默认值为 [`public/favicon.svg`](https://npmcn.com/package/%40authhero/admin/public/favicon.svg)。 。 。 .

## 部署到云旗页面

管理员是一个静态的SPA,所以任何静态主机都有效. Cloudflare Pages是推荐的目标.

在云浮仪表板, **工人页 – 创建页 – 连接到 Git**,则:

| 设置 | 数值 |
| --- | --- |
| 构建命令 | `pnpm install --no-frozen-lockfile && pnpm --filter "@authhero/admin..." build` |
| 构建输出目录 | `dist` |
| 根目录( 高级) | `apps/admin` |
| 环境变量 | `NODE_VERSION=20`, (中文(简体) ), `ENABLE_EXPERIMENTAL_COREPACK=1`,加上 `VITE_*` 从上表设置 |

线索 `...` 需要pnpm过滤器——它构建管理员的工作空间依赖性(特别是 `@authhero/adapter-interfaces`)在管理本身之前。 没有它,Vite就无法解决 `@authhero/adapter-interfaces` 因为共通软件包没有构建 `dist/`。 。 。 .

对于SPA客户端路由,添加 [`public/_redirects`](https://npmcn.com/package/%40authhero/admin/public/_redirects)数字 :

```text
/*    /index.html   200
```

### 多个 Cloudflare 账户

Cloudflare的"Git"集成将回放绑入了单一Cloudflare账户. 要在多个账户中部署相同的代码库,你有两种选择:

1.  **GitHub 动作 + Wrangler** 将 Pages Git 集成和部署从CI 与 `cloudflare/wrangler-action`,提供每个账户的 `CLOUDFLARE_API_TOKEN` 财务报告和审定财务报表 `CLOUDFLARE_ACCOUNT_ID` 作为独立的 GitHub 秘密。 构建一次, 通过矩阵任务部署 N 次 。 每个账户 `VITE_*` 值可以在构建时设定为工作流程内存, 或者使用运行时 `window.__AUTHHERO_ADMIN_CONFIG__` 运送一件文物.
2.  **每个环境的叉子** ——将回放分出到Cloudflare账户的每个组织中,并将每个分出分出分出分出分出分出的项目与自己的分出分出分出分出. 更低的设置成本,其代价是必须进行上游合并并保持叉的同步.

## 结构说明

-   **双路由器**: 位于 [`src/index.tsx`](https://npmcn.com/package/%40authhero/admin/src/index.tsx) 处理域选择( t)`/`租户管理`/tenants/*`),按租户计的管理人员`/:tenantId/*`)和OAuth调用(`/auth-callback`) (中文(简体) ). 内部路由器在 [`src/App.tsx`](https://npmcn.com/package/%40authhero/admin/src/App.tsx) 是安装在 `basename="/:tenantId"`。 。 。 .
-   **认证**数字 : `@auth0/auth0-spa-js` 相对于配置 `domain`编号 :`clientId`编号 :`audience`提供方居住在 [`src/authProvider.ts`](https://npmcn.com/package/%40authhero/admin/src/authProvider.ts)。 。 。 .
-   **数据**: 自定义数据提供者 [`src/auth0DataProvider.ts`](https://npmcn.com/package/%40authhero/admin/src/auth0DataProvider.ts) 与AuthHero管理API交谈.

见完整文件 [authhero.net/apps/admin/ (英语)](https://authhero.net/apps/admin/)。 。 。 .

## 常见问题

### @authhero/admin 是什么？

AuthHero admin UI – a Vite \+ React 19 SPA 用于管理租户,用户,应用程序,连接,角色,品牌等多个AuthHero部署\.

### 如何安装 @authhero/admin？

在项目目录运行 npm install @authhero/admin，或使用 pnpm add / yarn add / bun add。

### @authhero/admin 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/authhero\_\_admin 是否存在。

### @authhero/admin 支持 ESM 还是 CommonJS？

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

### @authhero/admin 可以商用吗？

@authhero/admin 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @authhero/admin 的下载量有多少？

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

### @authhero/admin 还在维护吗？

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