JSR 项目中忽略 index.js 和 index.d.ts 文件的构建问题分析

在 JSR 项目中，开发者可能会遇到一个常见问题：当构建 tarball 包时，项目中的 index.js 和 index.d.ts 文件被意外忽略。这种情况通常会导致发布失败，并显示"invalid 'exports' field"的错误提示。

问题现象

当开发者配置了 deno.json 文件，指定了 exports 字段指向 index.js 文件时，构建过程中会出现以下两种表现：

1. 在 dry-run 模式下，输出结果显示缺少 index.js 和 index.d.ts 文件
2. 实际发布时会报错，提示 exports 字段引用的入口文件不存在

根本原因

经过分析，这个问题通常是由于项目中存在 .gitignore 文件导致的。JSR 的构建系统会将 deno.json 中的 exclude 配置与 .gitignore 规则叠加使用，而不是覆盖关系。这意味着：

• 即使你在 deno.json 中明确指定了要包含的文件
• 如果这些文件被 .gitignore 规则匹配到，它们仍然会被排除在构建结果之外

特别值得注意的是，这种影响不仅限于当前目录下的 .gitignore 文件，还包括父级目录中的 .gitignore 规则。

解决方案

针对这个问题，有以下几种解决方法：

1. 检查并修改 .gitignore 文件：确保你的 index.js 和 index.d.ts 文件没有被 .gitignore 规则排除

2. 使用 include 字段替代：在 deno.json 中明确列出所有需要包含的文件，而不是依赖 exclude 规则

3. 添加 ! 排除规则：在 .gitignore 中使用 ! 前缀来特别包含某些文件，例如：

   !index.js
   !index.d.ts
   

最佳实践建议

为了避免类似问题，建议开发者在发布 JSR 包时：

1. 始终检查 dry-run 输出，确认所有必要文件都被包含
2. 对于关键入口文件，使用 include 字段明确指定
3. 保持 .gitignore 规则的简洁性，避免过度排除
4. 考虑将构建产物与源代码分离，使用不同的目录结构

未来改进方向

虽然当前可以通过文档指导开发者解决这个问题，但从用户体验角度，JSR 团队可以考虑：

1. 在构建时提供更明确的警告信息，当关键文件被忽略时
2. 改进错误提示，明确指出哪些文件被 .gitignore 排除
3. 考虑调整 exclude 与 .gitignore 的交互逻辑，使其更符合开发者预期

通过理解这个问题的本质和解决方案，开发者可以更顺利地完成 JSR 包的构建和发布流程。