生产工程基线

核验快照：2026-08-02，稳定版 Bun 1.3.14。生产项目应固定团队已验证的稳定版本或镜像 digest，而不是永久固定本文版本。

基线解决什么

这套基线把“Bun 能运行代码”和“项目可以稳定发布”分开：Bun 执行 TypeScript，但类型检查、Lint、测试、数据库迁移、镜像扫描和回滚仍需要显式流程。

{
  "name": "bun-service",
  "private": true,
  "type": "module",
  "packageManager": "bun@1.3.14",
  "scripts": {
    "dev": "bun --watch src/index.ts",
    "start": "bun run --no-env-file dist/index.js",
    "typecheck": "tsc --noEmit",
    "check": "biome check .",
    "test": "bun test --isolate",
    "test:ci": "bun test --parallel --coverage",
    "build": "bun build src/index.ts --target=bun --production --outdir=dist",
    "ci": "bun run typecheck && bun run check && bun run test:ci && bun run build"
  },
  "trustedDependencies": []
}

示例选择 Biome 作为一个明确的 Lint/Formatter 执行者，需要安装对应开发依赖。已有稳定 ESLint 或 Oxlint 流程的仓库应替换 check 命令，而不是重复执行大量相同规则。

TypeScript 6.0 起不再自动发现所有 @types/* 包；使用 Bun 全局类型时需要安装 @types/bun 并显式列出 "types": ["bun"]。如果项目还使用 Node、测试框架或 React 类型，也要把对应类型包加入数组。

可复现 CI

name: ci
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.14
      - run: bun ci
      - run: bun run ci

bun ci 等价于 bun install --frozen-lockfile。minimumReleaseAge 只影响新解析的版本，已经存在于 bun.lock 的版本不会因此自动被替换；安全升级仍需要审计和显式锁文件变更。

安装脚本是代码执行授权

bun pm untrusted
bun pm trust <reviewed-package>
bun audit

只允许经过审查、确实需要构建步骤的依赖进入 trustedDependencies。bun audit --prod 自 Bun 1.2.21 起可只审计生产依赖，但不支持 --production 或 --omit=dev 写法，且在 Workspace 根目录存在已知过滤缺陷（oven-sh/bun#26675），CI 依赖其结果前应在目标仓库结构下实测。--exact 固定直接依赖范围，bun.lock 才负责完整依赖图的可复现性，两者不能互相替代。

生产环境变量

Bun 默认会读取 .env 系列文件。容器或受管平台已经注入生产变量时，使用 --no-env-file 避免意外读取打包进镜像或挂载目录的本地文件：

bun run --no-env-file dist/index.js

启动时验证必需变量，日志只记录变量名和状态，不记录值。浏览器 bundle、错误页面、Trace 和 Agent 上下文不得包含服务端密钥。

发布门禁

• 类型检查、Lint、单元、集成和端到端测试；
• 目标数据库上的迁移预演和回滚方案；
• 目标 OS、CPU、libc 和 Bun 版本上的启动测试；
• SIGTERM、长连接关闭和 readiness 切流测试；
• 容器与依赖漏洞扫描；
• 冷启动、内存、并发和持续负载测试；
• Canary 只用于独立兼容测试，不能替代稳定版本发布门禁。

官方参考：TypeScript 6/7、bun install、Test configuration、Environment variables。