name: bknd-local-setup description: 用于在本地设置新 Bknd 项目或配置本地开发环境。涵盖 CLI 安装、项目创建、运行时适配器、配置文件设置和开发服务器选项。

本地开发环境设置

从零开始设置 Bknd 本地开发环境。

先决条件

Node.js 18+ 或 Bun 1.0+
npm、yarn、pnpm 或 bun 包管理器
终端/命令行访问权限

何时使用 UI 模式

在 http://localhost:3000/admin 浏览管理面板
可视化探索实体和数据
手动测试身份验证流程

注意： 初始项目设置需要 CLI/代码。

何时使用代码模式

创建新的 Bknd 项目
配置数据库连接
定义模式
运行开发服务器
所有初始设置任务

代码方法

步骤 1：创建新项目（交互式）

最快启动方式：

# 交互式项目创建
npx bknd create my-app

# 跟随提示：
# - 项目名称
# - 数据库类型（推荐 SQLite 用于本地开发）
# - 包含示例模式？

这创建项目结构包括：

bknd.config.ts - 主配置
package.json - 依赖项
.env - 环境变量模板

步骤 2：安装依赖项

cd my-app

# npm
npm install

# bun（更快）
bun install

# pnpm
pnpm install

步骤 3：运行开发服务器

# 默认（端口 3000，基于文件的 SQLite）
npx bknd run

# 内存数据库（原型设计最快，重启后数据丢失）
npx bknd run --memory

# 自定义端口
npx bknd run --port 8080

# 不自动打开浏览器
npx bknd run --no-open

# 显式指定运行时
npx bknd run --server bun
npx bknd run --server node

服务器在 http://localhost:3000 启动，包括：

API：/api/data/*、/api/auth/*、/api/media/*
管理 UI：/admin

替代方案：手动设置

步骤 1：初始化包

mkdir my-bknd-app && cd my-bknd-app
npm init -y
npm install bknd

步骤 2：创建配置文件

创建 bknd.config.ts：

import type { CliBkndConfig } from "bknd";
import { em, entity, text, boolean } from "bknd";

// 定义模式
const schema = em({
  todos: entity("todos", {
    title: text().required(),
    done: boolean(),
  }),
});

// 注册类型
type Database = (typeof schema)["DB"];
declare module "bknd" {
  interface DB extends Database {}
}

export default {
  app: (env) => ({
    connection: {
      url: env.DB_URL ?? "file:data.db",
    },
    schema,
  }),
} satisfies CliBkndConfig;

步骤 3：创建入口文件（可选）

对于程序化控制，创建 index.ts：

import { serve } from "bknd/adapter/bun";
import { em, entity, text, boolean } from "bknd";

const schema = em({
  todos: entity("todos", {
    title: text().required(),
    done: boolean(),
  }),
});

serve({
  connection: { url: "file:data.db" },
  config: {
    data: schema.toJSON(),
  },
});

运行：

# Bun
bun run index.ts

# Node（需要 tsx 或 ts-node）
npx tsx index.ts

运行时适配器

Bun（推荐速度快）

import { serve } from "bknd/adapter/bun";

serve({
  connection: { url: "file:data.db" },
});

Node.js

import { serve } from "bknd/adapter/node";

serve({
  connection: { url: "file:data.db" },
});

框架集成

Next.js：

// app/api/bknd/[[...bknd]]/route.ts
import { createHandler } from "bknd/adapter/nextjs";
export const { GET, POST, PUT, DELETE, PATCH } = createHandler(config);

Astro：

// src/pages/api/[...bknd].ts
import { createHandler } from "bknd/adapter/astro";
export const ALL = createHandler(config);

React Router（Remix）：

// app/routes/api.$.tsx
import { createHandler } from "bknd/adapter/react-router";
export const loader = createHandler(config);
export const action = createHandler(config);

CLI 选项参考

选项	描述	默认
`-p, --port <port>`	服务器端口	3000
`-m, --memory`	使用内存数据库	-
`--server <server>`	运行时：`node` 或 `bun`	自动检测
`--no-open`	不自动打开浏览器	默认打开
`-c, --config <path>`	配置文件路径	自动检测
`--db-url <url>`	数据库 URL 覆盖	-

配置文件检测

Bknd 自动检测配置文件（按顺序）：

bknd.config.ts
bknd.config.js
bknd.config.mjs
bknd.config.cjs
bknd.config.json

项目结构

框架集成布局

my-nextjs-app/
├── app/
│   ├── api/
│   │   └── bknd/
│   │       └── [[...bknd]]/
│   │           └── route.ts
│   └── admin/
│       └── page.tsx
├── bknd.config.ts
├── bknd-types.d.ts
└── .env.local

生成 TypeScript 类型

定义模式后，生成类型用于 IDE 支持：

# 生成到 bknd-types.d.ts（默认）
npx bknd types

# 自定义输出
npx bknd types -o types/bknd.d.ts

# 打印到控制台（调试）
npx bknd types --dump

本地开发的数据库选项

数据库	URL 格式	最适合
内存 SQLite	`:memory:` 或 `--memory` 标志	快速原型设计
文件 SQLite	`file:data.db`	持久本地开发
LibSQL（Turso）	`libsql://your-db.turso.io`	远程开发数据库

内存（临时）

npx bknd run --memory

数据在服务器重启时重置。最适合快速原型设计。

基于文件的 SQLite（持久）

npx bknd run
# 或显式：
npx bknd run --db-url "file:data.db"

数据持久保存在 data.db 文件中。

重置数据库

# 删除 SQLite 文件以重新开始
rm data.db

# 然后重启服务器
npx bknd run

热重载

模式更改需要服务器重启。使用监视模式：

# Bun
bun --watch index.ts

# Node 使用 nodemon
npx nodemon --exec "npx bknd run"

调试命令

# 显示内部路径
npx bknd debug paths

# 显示所有注册的路由
npx bknd debug routes

# CLI 帮助
npx bknd --help
npx bknd run --help

验证

设置后，验证一切正常工作：

1. 服务器运行：

curl http://localhost:3000/api/data
# 应返回实体列表

2. 管理面板可访问： 在浏览器中打开 http://localhost:3000/admin

3. 类型生成：

npx bknd types
# 检查 bknd-types.d.ts 是否创建

常见陷阱

配置文件未找到

问题： Config file could not be resolved 错误

修复： 确保配置文件存在且扩展名正确：

# 检查文件是否存在
ls bknd.config.*

# 或显式指定
npx bknd run -c ./bknd.config.ts

端口已被使用

问题： EADDRINUSE: address already in use

修复： 使用不同端口或终止现有进程：

# 使用不同端口
npx bknd run --port 3001

# 或查找并终止进程
lsof -i :3000
kill -9 <PID>

数据库权限错误

问题： SQLITE_CANTOPEN: unable to open database file

修复： 确保目录有写入权限：

# 检查权限
ls -la

# 修复权限
chmod 755 .

使用 em() 时的 TypeScript 错误

问题： 使用 em() 返回值时类型错误

修复： 记住 em() 只返回模式定义，不是 EntityManager：

// 错误 - em() 仅是模式构建器
const em = em({ ... });
em.repo("posts").find();  // 错误

// 正确 - 使用 api.data 进行查询
const api = new Api({ url: "http://localhost:3000" });
api.data.readMany("posts");

Bun 未找到

问题： bun: command not found

修复： 安装 Bun 或使用 Node：

# 安装 Bun
curl -fsSL https://bun.sh/install | bash

# 或使用 Node 运行时
npx bknd run --server node

Windows 路径问题

问题： Windows 上文件路径未解析

修复： 使用正斜杠：

// 错误
connection: { url: "file:C:\\data\\my.db" }

// 正确
connection: { url: "file:C:/data/my.db" }
// 或相对路径
connection: { url: "file:data.db" }

该做和不该做的事

该做：

使用 --memory 标志进行快速实验
使用 file:data.db 进行持久开发
模式更改后生成类型
将 bknd.config.ts 提交到版本控制
使用 .env 用于环境特定值

不该做：

将 data.db 提交到版本控制（添加到 .gitignore）
提交包含秘密的 .env（使用 .env.example 模板）
需要数据持久性时使用内存数据库
模式更改后忘记重启服务器
尝试将 em() 结果用作 EntityManager

Bknd本地开发环境设置Skill bknd-local-setup