# @bagelink/workspace 中文文档

规范地址：https://npmcn.com/package/%40bagelink/workspace/

版本：1\.20\.64
npm 元数据更新时间：2026-11-06T16:49:09.219Z
中文译文更新时间：2026-11-07T14:53:08.857Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：236 kB，48 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vite \>=5\.0\.0，@bagelink/sdk \>=1\.0\.0
- 首次发布：2026-01-12T03:27:29.157Z
- 最新版本发布：2026-11-06T16:49:08.960Z
- 近 30 天下载量：16319（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：531（近 12 个月 531 个）

## 中文简介

用于 Bagel 项目的 Monorepo 工作空间工具, 并配有代理和配置管理

## 安装

```sh
npm install @bagelink/workspace
```

也可以使用：`pnpm add @bagelink/workspace`、`yarn add @bagelink/workspace`、`bun add @bagelink/workspace`

## README

# @ bagelink/ 工作空间

Bagel项目的工作空间工具----既为单一项目工作,也为单列项目工作.

## 特征

-   🔧 **简单配置**: 所有环境的一个配置文件
-   🔀 **代理管理**: Vite dev 代理 + Netlify 生产重定向
-   🏗️ **构建工具**: 使用环境注入的自发遗传网
-   📦 **莫诺雷波支持**: 多项目设置的连锁配置

## 安装

```bash
pnpm add @bagelink/workspace
```

## 快速启动

### 备选案文1:运行 `npx bgl init` (建议)

```bash
npx bgl init

🔧 No bgl.config.ts found. Let's create one!

? What is your Bagel project ID? › my-project
? Use custom production host? › No / Yes
? Add/update dev scripts in package.json? › Yes
? Create/update vite.config.ts? › Yes
? Generate netlify.toml for deployment? › Yes

✅ Created bgl.config.ts
   Production host: https://my-project.bagel.to
   Local dev host: http://localhost:8000

✅ Updated package.json with dev scripts
✅ Created vite.config.ts
✅ Generated netlify.toml
```

这将:

-   创建 `bgl.config.ts` 使用您的工程配置
-   添加/覆盖 `dev` 财务报告和审定财务报表 `dev:local` 脚本在 `package.json`
-   创建 `vite.config.ts` 带有代理配置( 如果不存在)
-   生成 `netlify.toml` 带有生产代理配置

### 备选案文2:首次使用时自动

你第一次使用的时候 `@bagelink/workspace`,它将自动提示您创建配置文件,如果它不存在.

### 备选案文3:手工创建

创建 `bgl.config.ts`数字 :

```typescript
import { defineWorkspace } from '@bagelink/workspace'
import type { WorkspaceConfig, WorkspaceEnvironment } from '@bagelink/workspace'

/**
 * Define your workspace environments
 * You can add as many custom environments as needed (e.g., 'staging', 'preview')
 * Use --mode flag to switch: bgl dev --mode <env_name>
 */
const configs: Record<WorkspaceEnvironment, WorkspaceConfig> = {
  localhost: {
    host: 'http://localhost:8000',
    proxy: '/api', // Optional: remove to skip proxy setup
    openapi_url: 'http://localhost:8000/openapi.json',
  },
  development: {
    host: 'https://project.bagel.to',
    proxy: '/api',
    openapi_url: 'https://project.bagel.to/openapi.json',
  },
  production: {
    host: 'https://project.bagel.to',
    proxy: '/api',
  },
  // Add your own custom environments
  staging: {
    host: 'https://staging.project.bagel.to',
    proxy: '/api',
  },
}

export default defineWorkspace(configs)
```

## 使用量

### 1\. 增加类型定义

添加到您的项目 `env.d.ts`数字 :

```typescript
/// <reference types="@bagelink/workspace/env" />
```

这为注入的环境变量提供了TypeScript类型.

### 2\. 配置 Vite (`vite.config.ts`(中文(简体) )

**建议: 使用 Vite 插件( 保持您的配置干净并标准)**

```typescript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { bagelink } from '@bagelink/workspace/vite'
import workspace from './bgl.config'

export default defineConfig({
  plugins: [
    vue(),
    bagelink({ workspace }),
  ],
})
```

自动插件 :

-   基于 `bgl.config.ts`
-   设置 `@` 别名指向 `./src`
-   设置 `@shared` 别名( 单列)
-   保持你的 Vite.config.ts 干净和可扩展

**高级: 自定义选项**

```typescript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { bagelink } from '@bagelink/workspace/vite'
import { fileURLToPath } from 'node:url'
import workspace from './bgl.config'

export default defineConfig({
  plugins: [
    vue(),
    bagelink({
      workspace,
      config: {
        sharedPath: '../packages/shared',
        additionalAliases: {
          '@utils': fileURLToPath(new URL('./src/utils', import.meta.url))
        }
      }
    }),
  ],
})
```

**遗产: 手动代理设置**

```typescript
import { defineConfig } from 'vite'
import { createViteProxy } from '@bagelink/workspace'
import workspace from './bgl.config'

export default defineConfig(({ mode }) => {
  const config = workspace(mode as WorkspaceEnvironment)
  
  return {
    plugins: [vue()],
    server: {
      proxy: createViteProxy(config)
    }
  }
})
```

### 3\. 在您的应用程序中使用配置

**运行时访问配置 `useWorkspace()`数字 :**

```typescript
import { useWorkspace, getApiUrl } from '@bagelink/workspace'

// In your app setup
const { baseURL, proxy, host, mode } = useWorkspace()
const auth = createAuth({ baseURL }) // Uses proxy if available, otherwise host

// Or get full API URL
const apiUrl = getApiUrl() // 'https://project.bagel.to/api'
```

**Vue 组件示例 :**

```vue
<script setup lang="ts">
import { useWorkspace } from '@bagelink/workspace'
import { createAuth } from '@bagelink/auth'

const { baseURL, proxy, host, mode } = useWorkspace()
const auth = createAuth({ baseURL }) // Uses proxy if available, otherwise host

console.log('API Host:', host)
console.log('Environment:', mode)
</script>
```

**访问原始环境变量 :**

```typescript
// These are injected at build time by the bagelink plugin
const proxy = import.meta.env.VITE_BGL_PROXY        // '/api'
const host = import.meta.env.VITE_BGL_HOST          // 'https://project.bagel.to'
const openapi = import.meta.env.VITE_BGL_OPENAPI_URL // optional
```

### 4\. 添加脚本到 `package.json`

```json
{
  "scripts": {
    "dev": "vite",
    "dev:local": "vite --mode localhost",
    "dev:staging": "vite --mode staging",
    "build": "vite build",
    "build:staging": "vite build --mode staging"
  }
}
```

### 5\. 自定义环境

您可以定义您需要的多少自定义环境 。 环境名称是完全灵活的:

```typescript
const configs: Record<WorkspaceEnvironment, WorkspaceConfig> = {
  localhost: {
    host: 'http://localhost:8000',
    proxy: '/api',
  },
  development: {
    host: 'https://dev.project.bagel.to',
    proxy: '/api',
  },
  staging: {
    host: 'https://staging.project.bagel.to',
    proxy: '/api',
  },
  preview: {
    host: 'https://preview.project.bagel.to',
    // No proxy - will use host directly
  },
  production: {
    host: 'https://project.bagel.to',
    proxy: '/api',
  },
}
```

使用 `--mode` 要切换环境的旗帜 :

```bash
# Development
bgl dev --mode development

# Staging
bgl dev --mode staging

# Production build
bgl build --mode production
```

**说明:** 这个 `proxy` 字段是可选的。 如果省略, 将不会为此环境配置代理, 并且 `baseURL` 从 `useWorkspace()` 将返回 `host` 数值.

### 6\. 产生网络化配置

```typescript
import { writeNetlifyConfig } from '@bagelink/workspace'
import workspace from './bgl.config'

const config = workspace('production')
writeNetlifyConfig(config, './netlify.toml')
```

## 莫诺雷波支持

### 根配置( R)`/bgl.config.ts`(中文(简体) )

```typescript
import { defineWorkspace } from '@bagelink/workspace'

export default defineWorkspace({
  localhost: {
    host: 'http://localhost:8000',
    proxy: '/api',
  },
  development: {
    host: 'https://shared.bagel.to',
    proxy: '/api',
  },
  production: {
    host: 'https://shared.bagel.to',
    proxy: '/api',
  },
})
```

### 项目重叠( E)`/projects/admin/bgl.config.ts`(中文(简体) )

```typescript
import { defineWorkspace } from '@bagelink/workspace'
import rootWorkspace from '../../bgl.config'

export default defineWorkspace({
  localhost: rootWorkspace('localhost'),
  development: rootWorkspace('development'),
  production: {
    ...rootWorkspace('production'),
    host: 'https://admin.bagel.to', // Override
  },
})
```

## 国 际

### 单一工程设置

#### `npx bgl init`

交互生成项目配置文件 :

-   `bgl.config.ts` - 工作空间配置
-   `package.json` - 添加/更新dev脚本(可选)
-   `vite.config.ts` - Vite 代理配置( 可选)
-   `netlify.toml` - 将部署配置网化(可选)

```bash
npx bgl init
```

**特征 :**

-   项目ID和主机配置提示
-   添加/覆盖 `dev` 财务报告和审定财务报表 `dev:local` 软件包中的脚本。 json
-   用代理设置创建 vite. config.ts( 如果不存在)
-   生成 netlify.toml 有生产代理配置
-   安全性:在每个步骤前提示

### 工作空间( 多项目) 设置

#### `npx bgl init --workspace`

为多个项目创建一个具有平面结构的工作空间:

```bash
npx bgl init --workspace

? Workspace name: › my-workspace
? Bagel project ID: › my-project
? Create first project? › Yes
? First project name: › web

✅ Workspace created successfully!
```

**创建结构 :**

```
my-workspace/
├── package.json          # Workspace root
├── bgl.config.ts         # Shared config
├── tsconfig.json
├── shared/               # Shared code
│   ├── package.json
│   ├── utils/
│   └── types/
└── web/                  # First project
    ├── bgl.config.ts
    ├── package.json
    ├── vite.config.ts
    └── src/
```

#### `bgl add <project-name>`

添加新工程到工作空间 :

```bash
bgl add admin
bgl add customer
bgl add mobile
```

每个项目:

-   在根级别获得自己的目录
-   从工作空间根继承共享配置
-   可以从 `shared/utils`, (中文(简体) ), `shared/types`等 (中文(简体) ).
-   带有 Vite 代理服务器的自动配置

#### `bgl list`

列出工作空间中的所有工程 :

```bash
bgl list

Projects:
  - web
  - admin
  - customer
```

### 运行工作空间项目

```bash
# Run all projects concurrently
bun run dev

# Run specific project
bun run dev:admin
bun run dev:customer

# Build specific project
bun run build:admin

# Build all projects
bun run build
```

**Vite 自动指定端口 :**

-   第一个项目: `http://localhost:5173`
-   第二个项目: `http://localhost:5174`
-   第三个项目: `http://localhost:5175`
-   包括:.

### 启动设置

#### `bgl lint init`

在您的工程中设置起伏和格式:

```bash
bgl lint init

? Select configurations to set up:
  ✔ ESLint
  ✔ Prettier
  ✔ EditorConfig
  ○ Git Hooks
? Install dependencies? › Yes

✅ Created eslint.config.js
✅ Created .prettierrc
✅ Created .prettierignore
✅ Created .editorconfig
✅ Updated package.json with lint scripts
```

**创建 :**

-   `eslint.config.js` - ESLint配置(第3版+类型脚本)
-   `.prettierrc` - 高级配置
-   `.prettierignore` - Pretier 忽略模式
-   `.editorconfig` - 编辑器配置
-   `.lintstagedrc` - 分级配置(如果选中了接钩)

**添加脚本 :**

-   `bun run lint` - 运行天线
-   `bun run lint:fix` - 解决起伏问题
-   `bun run format` - 格式代码
-   `bun run format:check` - 检查格式

**自动检测工作空间 :**

```bash
# In workspace root (auto-detected)
bgl lint init
✓ Detected workspace mode
# Sets up at workspace root

# In single project (auto-detected)
bgl lint init
# Sets up in current project

# Force modes:
bgl lint init --workspace  # Force workspace mode
bgl lint init --project    # Force single project mode
```

**工作空间检测 :**

-   检查 `workspaces` 选项
-   检查多个工程目录
-   自动应用最佳模式

### SDK 生成

#### `bgl sdk generate`

从 OpenAPI 规格生成类型SDK :

```bash
bgl sdk generate

? OpenAPI spec URL: › http://localhost:8000/openapi.json
? Output directory: › ./src/api
? Split into organized files? › Yes

📡 Fetching OpenAPI spec from: http://localhost:8000/openapi.json
📁 Output directory: ./src/api

✅ Generated types.d.ts
✅ Generated api.ts
✅ Generated index.ts
🔀 Splitting into organized files...
✅ Files organized into directories

✅ SDK generated successfully!

Import it in your code:
  import { api } from './api'
```

**特征 :**

-   自动读取 `openapi_url` 从 `bgl.config.ts`
-   从 OpenAPI 计划生成类型脚本
-   创建类型安全 API 客户端
-   可选文件组织( 由端点分割)
-   本地和远程 OpenAPI 规格的工程

**自动检测工作空间 :**

```bash
# In workspace root (auto-detected)
bgl sdk generate
✓ Detected workspace mode - will generate for multiple projects

? Select projects to generate SDK for:
  ✔ admin
  ✔ customer
  ✔ mobile

# In single project (auto-detected)
bgl sdk generate
# Generates SDK for current project only

# Force modes:
bgl sdk generate --workspace  # Force workspace mode
bgl sdk generate --project    # Force single project mode
```

**聪明行为 :**

-   自动检测工作空间结构
-   工作空间模式下的项目选择提示
-   读取 `openapi_url` 从每个项目的 `bgl.config.ts`

**生成结构 :**

```
src/api/
├── index.ts          # Main export
├── types.d.ts        # TypeScript types
└── api.ts            # API client

# Or with --split:
src/api/
├── endpoints/
│   ├── users.ts
│   ├── auth.ts
│   └── data.ts
├── types/
│   └── index.ts
└── index.ts
```

### `npx bgl --help`

显示 CLI 帮助 .

## API 密码

### 运行时函数

#### `useWorkspace()`

运行时获得工作空间配置 。 配置在构建过程中作为环境变量被注入.

```typescript
import { useWorkspace } from '@bagelink/workspace'

const { baseURL, proxy, host, openapiUrl, mode } = useWorkspace()
```

**回返情况:**

```typescript
interface RuntimeWorkspaceConfig {
  baseURL: string        // proxy if available, otherwise host
  proxy?: string         // '/api' (optional)
  host: string           // 'https://project.bagel.to'
  openapiUrl?: string    // optional
  mode: string           // current environment (e.g., 'localhost', 'development', 'staging')
}
```

#### `getApiUrl()`

通过合并主机和代理机获取完整的API URL.

```typescript
import { getApiUrl } from '@bagelink/workspace'

const apiUrl = getApiUrl() // 'https://project.bagel.to/api'
```

### 配置函数

#### `defineWorkspace(configs)`

为所有环境定义工作空间配置 .

```typescript
const workspace = defineWorkspace({
  local: { host: 'http://localhost:8000', proxy: '/api' },
  development: { host: 'https://project.bagel.to', proxy: '/api' },
  production: { host: 'https://project.bagel.to', proxy: '/api' },
})
```

### `generateWorkspaceConfig(root?, configFile?)`

交互式生成 bgl.config.ts 文件(在找不到配置时称为自动).

### `generateWorkspaceConfigSync(projectId, root?, configFile?, customHost?)`

程序生成 bgl.config.ts 文件 .

```typescript
import { generateWorkspaceConfigSync } from '@bagelink/workspace'

generateWorkspaceConfigSync('my-project')
// Creates bgl.config.ts with host: https://my-project.bagel.to
```

### `createWorkspace(options?)`

创建具有async配置分辨率的工作空间实例(用于高级单列配置).

```typescript
const workspace = createWorkspace({ root: process.cwd() })

const config = await workspace.getConfig('production')
const proxy = workspace.createProxy(config)
workspace.generateNetlify(config, './netlify.toml')
```

### 构建时函数

可从下列网址获得这些资料: `@bagelink/workspace/vite`数字 :

#### `createViteProxy(config)`

生成 Vite 代理配置 .

```typescript
import { createViteProxy } from '@bagelink/workspace/vite'
```

#### `writeNetlifyConfig(config, outPath?, additionalConfig?)`

生成并写入netlify.toml文件.

```typescript
import { writeNetlifyConfig } from '@bagelink/workspace/vite'
```

#### `setBuildEnvVars(config)`

设定构建进程的环境变量 :

-   `BGL_PROXY_PATH` - 代理路径(例如, `/api`(中文(简体) )
-   `BGL_API_HOST` - API 主机 URL
-   `BGL_OPENAPI_URL` - OpenAPI 规格 URL

```typescript
import { setBuildEnvVars } from '@bagelink/workspace/vite'
```

## 许可证

麻省理工学院巴盖尔工作室

## 常见问题

### @bagelink/workspace 是什么？

用于 Bagel 项目的 Monorepo 工作空间工具, 并配有代理和配置管理

### 如何安装 @bagelink/workspace？

在项目目录运行 npm install @bagelink/workspace，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 bgl，可以用 npx bgl 直接运行。

### @bagelink/workspace 支持 TypeScript 吗？

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

### @bagelink/workspace 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bagelink/workspace 可以商用吗？

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

### @bagelink/workspace 的下载量有多少？

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

### @bagelink/workspace 还在维护吗？

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