JavaScript / TypeScript / 系统课时

构建与发布项目

构建与发布项目

一个可发布的 TypeScript 项目不能只做到“本地能跑”。你还需要把类型检查、构建输出、包内容验证和发布前检查串成一条可重复执行的流程,确保注册表最终收到的是可运行 JavaScript 和对应声明文件,而不是源码目录或缺失类型的半成品。

学习目标

  • 能把类型检查与构建拆成独立脚本,避免构建成功却隐藏类型问题。
  • 能生成并检查 JavaScript 与 .d.ts 声明文件。
  • 能在真正发布前用打包预检确认包内文件、入口和版本信息。

建立最小发布配置

下面以一个 Node.js ESM 库为例。源码位于 src,编译结果只进入 dist,发布包只包含构建产物。declaration 用于生成类型声明,rootDir 与 outDir 则让源码和产物边界保持清晰。

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "declaration": true,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

package.json 中把类型检查、清理和构建变成固定脚本,同时明确运行入口与类型入口。

json
{
  "name": "demo-ts-lib",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "typecheck": "tsc --noEmit",
    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
    "build": "npm run clean && tsc"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

源码可以保持很小,先验证整个发布链路:

ts
export function greet(name: string): string {
  return `Hello, ${name}!`;
}

配置文件本身不会产生控制台结果。验证方法是先安装依赖,再执行类型检查和构建;若 tsc 能识别配置且入口声明匹配,命令应以成功状态结束。

先类型检查再构建

把类型检查和构建分开有两个好处:CI 可以快速阻止类型错误;构建脚本则只负责刷新产物。执行:

bash
npm run typecheck
npm run build

预期输出

text
> demo-ts-lib@1.0.0 typecheck
> tsc --noEmit

> demo-ts-lib@1.0.0 build
> npm run clean && tsc

> demo-ts-lib@1.0.0 clean
> node -e "require('fs').rmSync('dist',{recursive:true,force:true})"

成功时 tsc 通常不会额外输出诊断信息,并以退出码 0 结束。接着检查构建产物,而不是只相信“命令没报错”。

bash
node -e "console.log(require('fs').readdirSync('dist').sort().join('\n'))"

预期输出

text
index.d.ts
index.js

如果缺少 .d.ts,优先检查 declaration;如果文件被输出到意外目录,检查 rootDir、outDir 和 include 是否覆盖了真实源码位置。

验证实际包内容

发布前最容易遗漏的问题不是编译,而是包里装错文件。files、.npmignore、入口字段和构建目录共同决定最终内容。使用 npm 的打包预检可以看到真正会进入 tarball 的文件,而且不会发布到注册表。

bash
npm pack --dry-run --json | node --input-type=module -e "let s=''; process.stdin.on('data',d=>s+=d).on('end',()=>{const r=JSON.parse(s)[0]; console.log(r.files.map(f=>f.path).sort().join('\\n')); console.log(r.filename);})"

预期结果

text
dist/index.d.ts
dist/index.js
package.json
demo-ts-lib-1.0.0.tgz

不同 npm 版本还可能输出大小、校验值等字段,但 dist/index.js、dist/index.d.ts 与 package.json 应出现在文件列表中。如果看到 src、测试夹具、密钥文件或本地配置,应先修正发布白名单再继续。

发布前做最后闸门

真正执行 npm publish 之前,至少确认四件事:工作区已提交或可追溯、版本号尚未在目标注册表使用、npm pack --dry-run 内容正确、当前身份对目标包具有发布权限。若项目使用 CI 发布,再把令牌放在受保护的密钥存储中,不要写入 package.json、源码或仓库配置。

发布失败时也按阶段判断:类型检查失败就回到源码;构建产物缺失就查 tsconfig.json;打包内容错误就查 files 与忽略规则;注册表拒绝则检查版本、认证和权限。这样可以把“构建问题”和“发布权限问题”隔离开,避免在最后一步才混合排查。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建与发布项目

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通