JavaScript / TypeScript / 系统课时
构建与发布项目
构建与发布项目
一个可发布的 TypeScript 项目不能只做到“本地能跑”。你还需要把类型检查、构建输出、包内容验证和发布前检查串成一条可重复执行的流程,确保注册表最终收到的是可运行 JavaScript 和对应声明文件,而不是源码目录或缺失类型的半成品。
学习目标
- 能把类型检查与构建拆成独立脚本,避免构建成功却隐藏类型问题。
- 能生成并检查 JavaScript 与
.d.ts声明文件。 - 能在真正发布前用打包预检确认包内文件、入口和版本信息。
建立最小发布配置
下面以一个 Node.js ESM 库为例。源码位于 src,编译结果只进入 dist,发布包只包含构建产物。declaration 用于生成类型声明,rootDir 与 outDir 则让源码和产物边界保持清晰。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"declaration": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src/**/*.ts"]
}package.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"
}
}源码可以保持很小,先验证整个发布链路:
export function greet(name: string): string {
return `Hello, ${name}!`;
}配置文件本身不会产生控制台结果。验证方法是先安装依赖,再执行类型检查和构建;若 tsc 能识别配置且入口声明匹配,命令应以成功状态结束。
先类型检查再构建
把类型检查和构建分开有两个好处:CI 可以快速阻止类型错误;构建脚本则只负责刷新产物。执行:
npm run typecheck
npm run build预期输出
> 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 结束。接着检查构建产物,而不是只相信“命令没报错”。
node -e "console.log(require('fs').readdirSync('dist').sort().join('\n'))"预期输出
index.d.ts
index.js如果缺少 .d.ts,优先检查 declaration;如果文件被输出到意外目录,检查 rootDir、outDir 和 include 是否覆盖了真实源码位置。
验证实际包内容
发布前最容易遗漏的问题不是编译,而是包里装错文件。files、.npmignore、入口字段和构建目录共同决定最终内容。使用 npm 的打包预检可以看到真正会进入 tarball 的文件,而且不会发布到注册表。
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);})"预期结果
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 与忽略规则;注册表拒绝则检查版本、认证和权限。这样可以把“构建问题”和“发布权限问题”隔离开,避免在最后一步才混合排查。