本指南提供了手动和自动化两种方法来发布这个 React Native 组件到 npm，包括用于简化发布工作流程的高级自动化发布系统。
- Node.js 和 npm: 确保已安装 Node.js（版本 14 或更高）
- npm 账户: 在 npmjs.com 创建账户
- Git: 用于版本控制和仓库管理
- Git 远程仓库: 正确配置并具有推送权限
npm login
# 输入你的 npm 用户名、密码和邮箱npm whoami
# 应该显示你的 npm 用户名npm view react-native-advanced-flatlist
# 如果包不存在，你会收到错误（这是好的！）本项目包含一个完整的自动化发布脚本，可处理版本管理、构建、测试、Git 操作和 NPM 发布，具有高级错误处理和回滚功能。
- 🚀 交互式版本选择 - 在 patch、minor 或 major 发布之间选择
- ✅ 全面的预检查 - Git 状态、NPM 认证、依赖项、网络连接
- 🔨 自动构建和测试 - 清理、编译、代码检查、类型检查和测试
- 📦 包验证 - 发布前确保包的完整性
- 🔄 Git 操作 - 自动提交、打标签和推送
- 📤 NPM 发布 - 发布到 registry 并验证
- 🎯 错误处理 - 失败时的回滚功能
- 📝 详细日志 - 完整的发布过程审计记录
- 🧪 试运行模式 - 在不进行实际更改的情况下测试流程
npm run release这将：
- 运行所有预检查
- 构建和测试项目
- 提示您选择版本类型（patch/minor/major）
- 显示版本变更并询问确认
- 处理所有 Git 操作
- 发布到 NPM
- 验证发布成功
# 试运行模式（无实际更改）
npm run release:dry
# 直接版本发布
npm run release:patch-auto # Patch 版本 (1.0.0 → 1.0.1)
npm run release:minor-auto # Minor 版本 (1.0.0 → 1.1.0)
npm run release:major-auto # Major 版本 (1.0.0 → 2.0.0)
# 传统简单命令
npm run release patch # Patch 发布 - Bug 修复
npm run release minor # Minor 发布 - 新功能
npm run release major # Major 发布 - 破坏性变更# 带选项的直接脚本执行
node scripts/release.js [选项]
选项:
--dry-run, -d 试运行模式（无实际更改）
--version, -v 指定版本类型 (patch|minor|major)
--skip-tests, -s 跳过测试执行
--help, -h 显示帮助信息# 试运行的交互式发布
node scripts/release.js --dry-run
# 自动化 patch 发布
node scripts/release.js --version patch
# 跳过测试的 minor 发布
node scripts/release.js --version minor --skip-tests
# 跳过测试的 major 版本试运行
node scripts/release.js -d -v major -s- ✅ Git 工作树状态（警告未提交的更改）
- ✅ 当前 Git 分支验证（推荐 main/master）
- ✅ NPM 认证状态
- ✅ 依赖项安装和健康检查
- ✅ 到 NPM registry 的网络连接
- 🧹 清理之前的构建产物
- 🔍 TypeScript 类型检查
- 📋 ESLint 代码质量检查（尝试自动修复）
- 🔨 项目编译
- 🧪 测试执行（如果未跳过）
- 📦 包完整性验证
- 📊 显示当前版本
- 🎯 交互式或自动化版本类型选择
- 📈 计算并预览新版本
- ✅ 用户确认版本更新
- 📝 更新 package.json
- 💾 提交版本更改
- 🏷️ 创建版本标签（v1.0.0 格式）
- ⬆️ 推送提交和标签到远程
- 📤 发布包到 NPM registry
- ⏳ 等待 registry 传播
- ✅ 验证发布成功
自动化脚本包含全面的错误处理：
- 失败时自动回滚（尽可能）
- 版本回滚 - 恢复 package.json 更改
- Git 回滚 - 删除提交和标签
- 详细错误日志 -
release.log中的完整审计记录 - 优雅失败 - 带有有用错误信息的干净退出
所有发布操作都记录到 release.log，包含：
- 所有操作的时间戳
- 逐步执行详情
- 错误信息和堆栈跟踪
- 发布持续时间和摘要
对于那些喜欢手动控制或需要了解底层流程的人，这里是逐步的手动方法。
检查你的 package.json 文件：
{
"name": "react-native-advanced-flatlist",
"version": "1.0.0",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"files": [
"lib/",
"src/",
"README.md",
"LICENSE"
]
}# 确保所有代码已提交
git status
# 确保你在正确的分支上（最好是 main/master）
git branch
# 验证你已登录 npm
npm whoami# 清理旧的构建文件（推荐）
npm run clean
# 重新构建项目（必需！）
npm run build
# 这会将 TypeScript 编译为 JavaScript + 类型定义# 预览将发布的内容而不创建实际文件
npm run publish:check
# 或
npm pack --dry-run
# 这可以帮助你：
# - 验证文件列表是否正确
# - 检查包大小
# - 确认 .npmignore 配置
# - 避免发布错误的内容cd example
npm install
npm link ../
# 发布前本地测试你的包选择适当的版本更新：
# 用于 bug 修复 (1.0.1 → 1.0.2)
npm version patch
# 用于新功能 (1.0.1 → 1.1.0)
npm version minor
# 用于破坏性变更 (1.0.1 → 2.0.0)
npm version major
# 或手动编辑 package.json 中的版本# 再次确认你已登录
npm whoami
# 确保是最新构建
npm run build
# 发布包
npm publish
# 你的包将发布到 npm# 验证发布成功
npm view react-native-advanced-flatlist
# 测试安装
npm install react-native-advanced-flatlist# 推送版本标签到 git
git push --tags
# 推送代码更改
git pushgit init
git add .
git commit -m "Initial commit: React Native Advanced FlatList v1.0.0"- 进入 github.com
- 点击 "New repository"
- 仓库名称：
react-native-advanced-flatlist - 描述："一个强大的 React Native FlatList 组件，支持分页、刷新、选择和加载状态"
- 设为 Public
- 不要使用 README 初始化（我们已经有了）
- 点击 "Create repository"
git remote add origin https://github.com/yourusername/react-native-advanced-flatlist.git
git branch -M main
git push -u origin main遵循语义化版本：
- Major (1.0.0 → 2.0.0): 破坏性变更
- Minor (1.0.0 → 1.1.0): 新功能，向后兼容
- Patch (1.0.0 → 1.0.1): Bug 修复，向后兼容
当前用于版本管理的 package.json 脚本：
{
"scripts": {
"release": "node scripts/release.js",
"release:dry": "node scripts/release.js --dry-run",
"release:patch-auto": "node scripts/release.js --version patch",
"release:minor-auto": "node scripts/release.js --version minor",
"release:major-auto": "node scripts/release.js --version major",
"release:patch": "npm version patch && npm publish",
"release:minor": "npm version minor && npm publish",
"release:major": "npm version major && npm publish"
}
}403 Forbidden: 包名已存在
- 解决方案：更改包名或联系所有者
402 Payment Required: 包名被保留
- 解决方案：选择不同的名称
ENEEDAUTH: 未登录
- 解决方案：运行
npm login
Permission denied: SSH 密钥问题
- 解决方案：使用 HTTPS URL 或设置 SSH 密钥
Repository not found: URL 错误
- 解决方案：验证仓库 URL
Working directory not clean: 有未提交的更改
- 解决方案：提交或暂存你的更改
Build failed: TypeScript 编译错误
- 解决方案：发布前修复 TypeScript 错误
Tests failed: 测试套件失败
- 解决方案：修复失败的测试或更新测试配置
# ❌ 错误方法 - 使用旧的构建文件
npm publish
# ✅ 正确方法 - 新鲜构建
npm run build
npm publish# 使用 npm pack --dry-run 检查文件包含
npm pack --dry-run
# 不应该包含：
# ❌ node_modules/
# ❌ .git/
# ❌ 测试文件
# ❌ .env 文件
# 应该包含：
# ✅ lib/ (编译文件)
# ✅ src/ (源文件)
# ✅ README.md
# ✅ package.json# ❌ 忘记更新版本
npm publish # 会失败：版本已存在
# ✅ 正确的工作流程
npm version patch
npm publish# 检查下载统计（发布后）
npm view react-native-advanced-flatlist downloads
# 检查包依赖
npm view react-native-advanced-flatlist dependencies
# 检查谁依赖你的包
npm view react-native-advanced-flatlist dependents对于自动化发布脚本：
node scripts/release.js --help检查详细日志：
cat release.log- 始终先测试 - 使用
npm run release:dry验证流程 - 干净的工作树 - 发布前提交更改
- 审查更改 - 使用
npm run pack-test检查将发布的内容 - 监控发布 - 验证包出现在 npmjs.com 上
- 保留日志 - 查看
release.log中的任何警告或问题
- 使用语义化版本 - 遵循 semver 版本选择指南
- 标记发布 - 使用 Git 标签进行版本管理
- 更新文档 - 保持 README 和 CHANGELOG 最新
- 发布前始终测试 - 使用
npm pack并本地测试 - 保持 .npmignore 更新 - 不要发布不必要的文件
- 写好提交信息 - 用于版本跟踪
- 监控下载量 - 定期检查 npm 统计
- 首选自动化发布 - 使用
npm run release保持一致性 - 使用试运行模式 - 执行前测试发布
- 审查自动化日志 - 检查
release.log中的问题
- 启用 2FA - 使用双因素认证保护你的 npm 账户
- 使用自动化令牌 - 在 CI/CD 管道中使用令牌而非密码
- 作用域包 - 考虑使用作用域包（@yourname/package）
要启用完全自动化的发布而无需每次进行 2FA 验证，你必须配置一个启用了"绕过 2FA"选项的 NPM 自动化令牌。
- 访问 https://www.npmjs.com/settings/YOUR_USERNAME/tokens
- 点击 "Generate New Token" → "Granular Access Token"
| 设置 | 推荐值 |
|---|---|
| Token name（令牌名称） | auto-publish |
| Description（描述） | 用于自动化发布 |
| ✅ 必须勾选此项 | |
| Allowed IP ranges（允许的 IP 范围） | （可选）留空表示任何 IP |
| Permissions（权限） | Read and write |
| Select packages（选择包） | All packages 或特定包 |
| Expiration Date（过期日期） | 设置合理的过期时间（如 1 年） |
- 点击 "Generate token"
- 重要：立即复制令牌 - 它只会显示一次！
- 令牌格式：
npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 为你的用户全局设置令牌
npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN_HERE这会将令牌保存到 ~/.npmrc（Windows 上是 C:\Users\USERNAME\.npmrc）。
在项目根目录创建 .npmrc 文件：
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
然后设置环境变量：
# Windows PowerShell
$env:NPM_TOKEN="npm_YOUR_TOKEN_HERE"
# Windows CMD
set NPM_TOKEN=npm_YOUR_TOKEN_HERE
# Linux/Mac
export NPM_TOKEN=npm_YOUR_TOKEN_HERE对于 GitHub Actions，将令牌添加为仓库密钥：
# .github/workflows/publish.yml
- name: Publish to npm
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}# 验证认证
npm whoami
# 应该输出你的 npm 用户名原因：令牌无效、已过期或未勾选"绕过 2FA"。
解决方案：
- 在 npmjs.com 上删除旧令牌
- 创建新令牌并勾选 ✅ "Bypass two-factor authentication (2FA)"
- 重新配置新令牌
原因：创建令牌时未勾选"绕过 2FA"选项。
解决方案：
- 访问 https://www.npmjs.com/settings/YOUR_USERNAME/tokens
- 删除有问题的令牌
- 创建新的细粒度访问令牌
- 重要：勾选 ✅ "Bypass two-factor authentication (2FA)"
- 重新配置新令牌
原因：令牌已过期或被手动撤销。
解决方案：
- 在 npmjs.com 上生成新令牌
- 更新
.npmrc文件中的令牌
- 设置过期日期 - 不要使用永不过期的令牌
- 限制包作用域 - 如果可能，将令牌限制为特定包
- 使用 IP 限制 - 如果部署 IP 是静态的，添加允许的 IP 范围
- 定期轮换令牌 - 定期更换令牌
- 永不提交令牌 - 如果
.npmrc包含令牌，将其添加到.gitignore - 使用环境变量 - 首选
${NPM_TOKEN}模式而非硬编码令牌
在此检查你的令牌状态：https://www.npmjs.com/settings/stark2018/tokens
| 令牌名称 | 创建时间 | 过期时间 | 绕过 2FA |
|---|---|---|---|
| auto-publish | 2025年12月24日 | 2026年3月24日 | ✅ 已启用 |
- 审查依赖 - 定期审计依赖项的漏洞
- 永不暴露凭据 - 脚本永不暴露 NPM 凭据
- 使用试运行验证 - 所有操作都可以在试运行模式下审查
- 回滚功能 - 最小化部分发布的风险
- 全面日志 - 为所有操作提供审计记录
- 仓库权限 - Git 操作需要适当的权限
用正确的 GitHub URL 更新你的 package.json：
{
"repository": {
"type": "git",
"url": "https://github.com/yourusername/react-native-advanced-flatlist.git"
},
"bugs": {
"url": "https://github.com/yourusername/react-native-advanced-flatlist/issues"
},
"homepage": "https://github.com/yourusername/react-native-advanced-flatlist#readme"
}- 进入你的 GitHub 仓库
- 点击 "Releases" → "Create a new release"
- 标签版本：
v1.0.0 - 发布标题：
v1.0.0 - 首次发布 - 描述：从 CHANGELOG.md 复制
- 点击 "Publish release"
将这些徽章添加到你的 README.md：
[](https://badge.fury.io/js/react-native-advanced-flatlist)
[](https://opensource.org/licenses/MIT)
[](http://www.typescriptlang.org/)- 创建演示 GIF/截图
- 添加组件运行时的可视化示例
- 在 README 中包含代码示例
- 在 Twitter 上分享
- 在 Reddit 上分享（r/reactnative）
- 在 React Native 社区论坛发帖
- 添加到 awesome-react-native 列表
- 写关于你的包的博客文章
- 更新依赖 - 保持依赖项最新
- 监控问题 - 回应 GitHub issues 和 npm 反馈
- 安全更新 - 及时处理安全漏洞
- 文档 - 随新功能更新文档
- 审查自动化 - 定期检查发布脚本性能
- Patch (1.0.1): Bug 修复，向后兼容
- Minor (1.1.0): 新功能，向后兼容
- Major (2.0.0): 破坏性变更
跟踪你的包成功情况：
- npm 下载量: 检查每周/每月下载量
- GitHub stars: 监控仓库星标
- Issues/PRs: 社区参与度
- Dependents: 其他使用你的包的包
如果需要废弃一个版本：
# 废弃特定版本
npm deprecate react-native-advanced-flatlist@1.0.0 "此版本存在安全漏洞"
# 废弃所有版本
npm deprecate react-native-advanced-flatlist "包不再维护"- 包构建成功（
npm run build） - 所有文件包含在构建中（
npm run pack-test） - README 内容完整
- 版本号正确
- Git 仓库干净并已打标签
- npm 登录成功（
npm whoami） - 包发布成功
- 安装测试通过（
npm install package-name） - 文档链接有效
- GitHub release 已创建（如适用）
- 自动化脚本已测试（
npm run release:dry）
你发布的包将包含：
react-native-advanced-flatlist/
├── lib/ # 编译后的 JavaScript 和 TypeScript 定义
│ ├── index.js
│ ├── index.d.ts
│ ├── AdvancedFlatList.js
│ └── AdvancedFlatList.d.ts
├── src/ # 源 TypeScript 文件
│ ├── index.ts
│ └── AdvancedFlatList.tsx
├── scripts/ # 发布自动化
│ └── release.js
├── package.json
├── README.md
├── CHANGELOG.md
└── LICENSE
# 自动化发布（推荐）
npm run release
# 测试发布流程
npm run release:dry
# 快速 patch 发布
npm run release:patch-auto
# 手动发布
npm version patch
npm publish
# 获取帮助
node scripts/release.js --help祝你包发布顺利！ 🚀
如有自动化发布系统的问题，请检查 release.log 文件或使用 --dry-run 进行故障排除。
- 考虑添加全面的测试
- 设置 CI/CD 管道（GitHub Actions）
- 添加更多使用示例
- 创建视频教程
- 写技术博客文章
- 参与 React Native 社区讨论
你的包现已上线，可供 React Native 社区使用！🚀
未来发布的快速开始：
# 进行你的更改
git add .
git commit -m "你的更改"
# 发布（选择适当的版本类型）
npm run release自动化脚本会处理其余一切！