企业官网建设流程全解析

• 金融科技

tsdown 内置 CI 环境自动检测能力，允许你在同一个tsdown.config.ts中根据"本地开发"还是"CI 流水线"动态切换构建特性，例如只在 CI 中运行包校验（publint / attw）、只在本地生成类型声明以加速流水线。阅读本文后，你将掌握 tsdown 的 CI 感知值语法（字符串、对象、配置函数三种形式）、全部支持该能力的配置项，以及可直接复制到真实项目（如本仓库 dinero.js 的打包与 GitHub Actions 流水线）中的典型 CI 配置方案。

概述：tsdown 如何检测 CI 环境

tsdown 使用is-in-ci包来检测当前进程是否运行在 CI 环境中。该检测覆盖了主流 CI 提供商，包括 GitHub Actions、GitLab CI、Jenkins、CircleCI、Travis CI 等。

检测结果以布尔值的形式暴露给配置系统：本地开发环境为false，CI 流水线中为true。基于这个布尔值，tsdown 提供了一套CI 感知（CI-aware）值，让所有相关选项都能根据环境自动决定启用或禁用，而不必在脚本里手动维护多份配置或读取环境变量。

CI 感知值：四种取值与语义

凡是支持 CI 感知能力的选项，都可以接受以下四种取值：

其中'ci-only'与'local-only'是 tsdown 引入的字符串标记。它们与布尔值true/false相互组合，使得"本地快、CI 严"的差异化构建成为配置层面的一等公民。

支持 CI 感知值的选项

以下选项均接受 CI 感知值：

• dts—— TypeScript 声明文件（.d.ts）生成
• publint—— 包配置校验（检查package.json的exports/main/module/types与实际产物是否匹配）
• attw—— "Are the types wrong" 类型解析校验
• report—— 打包体积报告
• exports—— 自动生成package.json的exports字段
• unused—— 未使用依赖检查
• devtools—— DevTools 集成
• failOnWarn—— 警告即失败（默认值为'ci-only'）

需要特别强调的是failOnWarn：它默认就是'ci-only'，也就是说 tsdown 默认在本地构建时容忍警告，而在 CI 中一旦出现警告就让构建以非零退出码失败。这是"本地开发不被打断、CI 发布前严格把关"的典型默认策略，详见 Log Level 文档 对failOnWarn的说明。

三种使用形式

CI 感知值可以按三种形式写入配置：直接写字符串、通过对象里的enabled字段、或在配置函数中读取ci布尔值。

字符串形式

对于布尔型开关类选项，直接传入 CI 感知字符串即可：

export default defineConfig({ dts: 'local-only', // Skip DTS in CI for faster builds publint: 'ci-only', // Only run publint in CI failOnWarn: 'ci-only', // Fail on warnings in CI only (default) })

上面的示例中：dts只在本地生成（CI 跳过以缩短流水线耗时）；publint只在 CI 运行（本地不发散噪音）；failOnWarn使用默认的 CI-only 语义，但显式写出可以增强配置的可读性。

对象形式

当选项本身需要携带配置对象（如publint、attw等）时，把 CI 感知值放到enabled字段中，其余字段照常配置：

export default defineConfig({ publint: { enabled: 'ci-only', level: 'error', }, attw: { enabled: 'ci-only', profile: 'node16', }, })

这里publint.level与attw.profile的完整取值说明见 Package Validation 文档：level可取'warning' | 'error' | 'suggestion'（attw 为'warn' | 'error'），profile可取'strict' | 'node16' | 'esm-only'，并支持ignoreRules屏蔽特定问题类型（如'false-cjs'、'cjs-resolves-to-esm'）。

配置函数形式

当配置以函数形式导出时，第二个参数的上下文中会携带ci布尔值，可在此基础上做任意条件逻辑：

export default defineConfig((_, { ci }) => ({ minify: ci, sourcemap: !ci, }))

例如上面的配置：CI 中启用压缩（minify: true）、关闭 sourcemap（减小产物与上传开销），本地则相反——不压缩便于调试、保留 sourcemap。这种方式适合无法用单一 CI 感知值表达的复合策略。

典型 CI 配置

把上述能力组合起来，一份面向发布流程的典型 CI 配置如下：

export default defineConfig({ entry: 'src/index.ts', format: ['esm', 'cjs'], dts: true, failOnWarn: 'ci-only', publint: 'ci-only', attw: 'ci-only', })

其策略可以解读为：产物始终同时输出 ESM 与 CJS 并生成类型声明；在 CI 中，任何构建警告都会使任务失败，且必须通过publint与attw两道包校验（两者都要求项目目录中存在package.json），确保发布前的包结构与类型解析正确。

仓库实战佐证：dinero.js 中的落地情况

本仓库（dinero.js）正是用 tsdown 作为库打包工具，可作为理解 CI 感知配置的真实参照。

在 packages/dinero.js/package.json 中，build脚本即为tsdown，开发依赖声明为"tsdown": "^0.20.1"，Node 运行时要求>=20.0.0。其打包配置见 packages/dinero.js/tsdown.config.ts：通过导出配置数组同时构建 ESM 与多套 UMD（production / development、常规入口 / bigint 入口），并显式开启dts: true、clean: true、minify、sourcemap，同时用define注入__DEV__/__TEST__等编译期常量。

与之配套的 CI 流水线见 .github/workflows/ci.yml：该 GitHub Actions 工作流在pull_request合并到main时触发，依次执行lint、types（Node 20/22/24 矩阵）、test（Node 20/22/24 矩阵）、build与size（打包体积检查）等工作。从这套流水线可以推断：当 tsdown 的failOnWarn、publint、attw被设置为'ci-only'时，它们会精确地在上述 CI 上下文中生效，而本地npm run build则保持宽松、快速——这正是 CI 感知值的典型应用场景。

相关选项与延伸阅读

• Package Validation（publint 与 attw 配置） ——publint、attw的完整参数、profile 与ignoreRules说明
• Log Level（日志级别与failOnWarn细节） ——logLevel与failOnWarn的默认值与 CI 语义
• TypeScript Declaration Files（dts 生成） ——dts选项的完整配置（sourcemap、compilerOptions、vue、oxc等）
• Auto-Generate Package Exports（exports 自动生成） ——exports选项及devExports、customExports进阶用法
• CLI Reference（全部命令行选项） —— 对应选项的 CLI 等价写法（如tsdown --publint、tsdown --attw）
• Configuration File（配置文件形式） —— 配置文件格式、多配置导出与 workspace 用法
• tsdown 技能总览（SKILL.md） —— 安装、快速上手与全部选项速查表

实践建议：发布型 npm 库项目应优先采用failOnWarn: 'ci-only'与publint/attw的 CI-only 组合，让本地开发保持零摩擦，同时让 CI 在合并前完成最严格的校验；对dts这类耗时步骤，可考虑'local-only'或配合isolatedDeclarations（见 option-dts 文档）在 CI 中加速。

• 金融科技