npm 包发布安全：一个配置失误的代价
3 月 31 日，Anthropic 的 Claude Code——一个月活数百万的 AI 编程助手——的完整源码被发现公开在了 npm 公共仓库上。512,000 行 TypeScript 代码，1,906 个文件，包含 44 个未发布功能的 feature flag 和内部模型代号。原因？发布时漏了一个 .npmignore 配置。
这不是什么高深的供应链攻击，也不是零日漏洞。就是一个工程师忘了排除 source map 文件。但后果是 GitHub 历史上增长最快的 repo——2 小时内 5 万星。
如果 Anthropic 这种级别的公司都会犯这个错，你的项目也有可能。这篇文章不是要嘲笑谁，而是帮你检查自己的发布流程有没有同样的漏洞。
为什么你应该关注 npm 发布安全
npm 生态每天处理超过 20 亿次下载。你发布到 npm 的任何东西都是永久公开的——即使你在几分钟内 unpublish，自动化爬虫和镜像已经抓走了。
常见的泄露内容：
- Source map 文件（
.map）：完整的原始源码，包括注释 - 环境变量文件（
.env、.env.local）：API 密钥、数据库密码 - 构建产物和缓存（
.next/、dist/debug/）：可能包含调试信息 - 测试文件和 fixtures：可能包含真实数据
- 内部文档：架构设计、安全审计报告
Claude Code 泄露的核心链条是：Bun 构建 → 默认生成 .map 文件 → .map 引用 R2 上的 zip → zip 包含完整源码 → npm publish 没排除 .map → 全球可见。
实操指南：5 步加固你的 npm 发布流程
第 1 步：用 files 字段做白名单，而不是用 .npmignore 做黑名单
Claude Code 泄露的根本原因是黑名单思维——"我要排除哪些文件"。但你永远无法列举所有不该发布的文件。
正确做法：在 package.json 里用 files 字段做白名单，只包含你明确知道该发布的文件：
{
"name": "your-package",
"files": [
"dist/**/*.js",
"dist/**/*.d.ts",
"README.md",
"LICENSE"
]
}
注意：files 字段不会排除 package.json、README.md、LICENSE 和 CHANGELOG.md——这些永远会被包含。但其他所有文件默认被排除。
第 2 步：发布前用 npm pack --dry-run 检查
这是最简单也最容易被忽略的一步。在 npm publish 之前，先看看到底会发布什么：
# 列出所有会被打包的文件
npm pack --dry-run
# 或者生成 tarball 然后手动检查
npm pack
tar -tzf your-package-1.0.0.tgz
把这个命令加入你的 CI/CD 流程，用脚本自动检查是否有敏感文件：
#!/bin/bash
# scripts/check-publish.sh
SENSITIVE_PATTERNS=("*.map" "*.env" ".env*" "*.pem" "*.key" "*secret*" "*credentials*")
FILES=$(npm pack --dry-run 2>&1)
for pattern in "${SENSITIVE_PATTERNS[@]}"; do
if echo "$FILES" | grep -q "$pattern"; then
echo "❌ 发现敏感文件: $pattern"
exit 1
fi
done
echo "✅ 发布内容检查通过"
第 3 步：显式禁用 source map 生成
不管你用什么构建工具，生产发布时都应该显式关闭 source map：
// webpack.config.js
module.exports = {
mode: 'production',
devtool: false, // 不要用 'source-map' 或 'hidden-source-map'
};
// vite.config.ts
export default defineConfig({
build: {
sourcemap: false,
},
});
// tsconfig.json
{
"compilerOptions": {
"sourceMap": false,
"declarationMap": false
}
}
如果你用 Bun（Claude Code 的构建工具）：
# bun build 默认生成 source map，必须显式关闭
bun build --no-sourcemap ./src/index.ts --outdir ./dist
第 4 步：添加 prepublishOnly 钩子做自动检查
在 package.json 里加一个发布前的自动检查脚本：
{
"scripts": {
"prepublishOnly": "npm run build && npm run test && node scripts/check-no-secrets.js"
}
}
// scripts/check-no-secrets.js
const { execSync } = require('child_process');
const output = execSync('npm pack --dry-run 2>&1', { encoding: 'utf8' });
const lines = output.split('\n');
const forbidden = ['.map', '.env', '.pem', '.key', 'secret', 'credential', '.DS_Store'];
const violations = [];
for (const line of lines) {
for (const pattern of forbidden) {
if (line.toLowerCase().includes(pattern)) {
violations.push(line.trim());
}
}
}
if (violations.length > 0) {
console.error('🚫 以下文件不应该被发布:');
violations.forEach(v => console.error(` - ${v}`));
process.exit(1);
}
console.log('✅ npm 包内容安全检查通过');
第 5 步：在 CI 中加入发布内容审计
GitHub Actions 示例：
# .github/workflows/publish-audit.yml
name: Publish Audit
on:
pull_request:
paths:
- 'package.json'
- '.npmignore'
- 'tsconfig.json'
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
- name: Check publish contents
run: |
npm pack --dry-run 2>&1 | tee pack-contents.txt
if grep -E '\.(map|env|pem|key)$' pack-contents.txt; then
echo "::error::发现不应发布的敏感文件"
exit 1
fi
常见问题
.npmignore 和 package.json 的 files 字段冲突时谁优先？
如果 files 字段存在，它的优先级最高。.npmignore 只在没有 files 字段时生效。最佳实践是只用 files，不用 .npmignore——白名单永远比黑名单安全。
我的 npm 包已经发布了敏感文件怎么办？
- 立即
npm unpublish your-package@affected-version（72 小时内可操作） - 轮换所有可能泄露的密钥和凭证
- 检查 npm 镜像和 CDN 缓存（unpkg、jsDelivr 等）是否仍有缓存
- 修复配置后发布新版本
注意：npm 的 unpublish 政策是 72 小时内可以撤回，但自动化爬虫可能在几分钟内就已经备份了你的包。预防永远比补救重要。
source map 到底会暴露什么？
Source map 是构建产物到原始源码的完整映射。一个 .map 文件通常包含：
- 完整的原始源代码（包括注释）
- 文件路径和目录结构
- 变量名、函数名（即使代码被混淆了）
- 有时还包含内联的 source content
Claude Code 的情况更极端——source map 指向了一个外部 zip 包，里面是未经任何处理的完整 TypeScript 源码。
JR Academy 相关资源
- Claude Code 工作流指南 — 了解 Claude Code 的正确打开方式
- JR Academy DevOps 课程 — 系统学习 CI/CD、安全发布流程和云原生部署
- Gemma 4 开发者指南 — 用开源模型构建你的 AI 应用
这篇文章由 Claude Code 源码泄露事件启发。安全不是事后补救的东西，是发布流程的一部分。花 10 分钟检查你的 npm 发布配置，总好过花 10 天做危机公关。
