# @freebuff/auth 中文文档
规范地址：https://npmcn.com/package/%40freebuff/auth/
版本：0\.1\.0
npm 元数据更新时间：2026-10-06T17:24:04.829Z
中文译文更新时间：2026-11-15T12:54:22.712Z
软件包许可：Apache-2\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40freebuff/auth
原文对照：https://npmcn.com/package/%40freebuff/auth/?lang=original
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：59.8 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：next \>=15，react \>=18
- 首次发布：2026-10-06T17:24:04.056Z
- 最新版本发布：2026-10-06T17:24:04.681Z
- 近 30 天下载量：22946（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）
## 中文简介
与 Freebuff 签约 : 在任何没有秘密的网站中加入 Freebuff 账户 。 OIDC + Cloudflare工人的PKCE, Bun, Node 和 Next.js.
## 安装
```sh
npm install @freebuff/auth
```
也可以使用：`pnpm add @freebuff/auth`、`yarn add @freebuff/auth`、`bun add @freebuff/auth`
## README
# 与 Freebuff 签约
`@freebuff/auth` 让有Freebuff帐号的人进入您的网站: Google、 GitHub 或 Apple 通过 Freebuff , 没有配置, 没有 秘密要保密 秘密要保密 您的服务器了解访问者是谁( Q)`sub`,并与其 同意他们的电子邮件、姓名和图片)。 它从来没有看到他们的密码, 提供商证书或Freebuff账户代号.
这是标准的 OpenID 连接(授权代码 + PKCE),带有 服务器侧会话,并随处运行 `fetch` 和网络加密 : Cloudflare Workers, Bun, Node 20+, Deno and Next.js. 互联网档案馆的存檔,存档日期2013-12-22.
## 1\. 获得客户身份
每个项目环境都有自己的公共客户身份证,由 project的创建者针对精确的回调 URL :
```sh
# Production: the site's real origin
npx @freebuff/auth register --project notes --name "Notes" \
--environment production --redirect-uri https://notes.example/auth/freebuff/callback
# Local development: any port on localhost
npx @freebuff/auth register --project notes --name "Notes" \
--environment development --redirect-uri http://localhost:8787/auth/freebuff/callback
```
它以您的 Freebuff CLI 登录方式( 或 `FREEBUFF_TOKEN`和 指纹 `FREEBUFF_CLIENT_ID`以及你网站的出处 这里有配置 也不是一个秘密。 重新运行是安全的; 添加一个 新设 `--redirect-uri` 当网站获得新域名时.
## 2\. 上马
### 云旗工人、邦克、德诺、霍诺
包好你的接线员 它服务于四个认证路线,维持会话 新鲜的,和制作 `getUser` 可在内部任何地方使用:
```ts
import { createFreebuffAuth } from '@freebuff/auth'
const auth = createFreebuffAuth({
clientId: env.FREEBUFF_CLIENT_ID,
baseUrl: 'https://notes.example', // your canonical origin
})
export default {
fetch: auth.wrap(async (request) => {
const user = await auth.getUser(request)
if (new URL(request.url).pathname.startsWith('/api/') && !user) {
return Response.json({ error: 'Sign in required' }, { status: 401 })
}
return app.fetch(request)
}),
}
```
见 [`examples/cloudflare-worker.ts`](https://npmcn.com/package/%40freebuff/auth/examples/cloudflare-worker.ts) (静态) 资产+API)和 [`examples/hono.ts`](https://npmcn.com/package/%40freebuff/auth/examples/hono.ts)。 。 。 .
### Next.js (App路由器) (英语)
```ts
// lib/freebuff.ts
import { createFreebuffNext } from '@freebuff/auth/next'
export const freebuff = createFreebuffNext({
clientId: process.env.FREEBUFF_CLIENT_ID!,
baseUrl: process.env.APP_ORIGIN!,
})
// app/auth/freebuff/[...freebuff]/route.ts
export const { GET, POST } = freebuff.handlers
// proxy.ts (middleware.ts before Next 16): refreshes sessions before render
export const proxy = freebuff.proxy
export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] }
// Any Server Component, Route Handler or Server Action
const user = await freebuff.getUser()
```
见 [`examples/nextjs`](https://npmcn.com/package/%40freebuff/auth/examples/nextjs)。 。 。 .
### 按钮和客户端状态( 反应)
```tsx
import { SignInWithFreebuff, SignOutButton, useFreebuffUser } from '@freebuff/auth/react'
// link to /auth/freebuff/signin, returns here
// a POST form; sign-out is never a link
const { user, isLoading } = useFreebuffUser() // reads /auth/freebuff/session
```
无反应: 链接到 `/auth/freebuff/signin?returnTo=/somewhere`签名 与 `