镜像自地址
https://github.com/lhly/search-syntax-pro.git
已同步 2026-10-20 14:27:47 +08:00
f32329ce19
添加自动打包脚本 package.js，支持从 dist 目录生成发布包 新增 PACKAGING.md 文档说明打包流程 更新 .gitignore 忽略 releases 目录 优化 manifest.json 主机权限配置 新增 CHANGELOG-PERMISSIONS.md 记录权限变更
259 行
5.8 KiB
Markdown
259 行
5.8 KiB
Markdown
# 📦 Chrome扩展打包指南
|
||
|
||
本文档说明如何将 SearchSyntax Pro 打包为可发布到 Chrome Web Store 的 ZIP 文件。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式一：完整打包流程（推荐）
|
||
|
||
```bash
|
||
npm run package
|
||
```
|
||
|
||
这个命令会：
|
||
1. 执行 TypeScript 编译
|
||
2. 运行 Vite 构建
|
||
3. 复制静态资源（manifest.json、icons、国际化文件）
|
||
4. 将 dist 目录打包为 ZIP 文件
|
||
|
||
### 方式二：仅打包（快速迭代）
|
||
|
||
如果你已经运行过 `npm run build`，可以直接打包：
|
||
|
||
```bash
|
||
npm run package:only
|
||
```
|
||
|
||
## 📁 输出文件
|
||
|
||
打包后会在项目根目录生成：
|
||
|
||
```
|
||
releases/
|
||
└── ssp-v{version}.zip
|
||
```
|
||
|
||
例如：`releases/ssp-v1.0.0.zip`
|
||
|
||
版本号自动从 `package.json` 读取。
|
||
|
||
## 🔍 打包内容
|
||
|
||
ZIP 包会包含 `dist/` 目录的所有必要文件：
|
||
|
||
- ✅ `manifest.json` - Chrome 扩展配置
|
||
- ✅ `background.js` - Service Worker（后台脚本）
|
||
- ✅ `popup.js` - 弹窗界面脚本
|
||
- ✅ `options.js` - 设置页面脚本
|
||
- ✅ `content.js` - 内容脚本
|
||
- ✅ `icons/` - 所有尺寸的图标（16x16, 32x32, 48x48, 128x128）
|
||
- ✅ `_locales/` - 国际化资源文件
|
||
- ✅ 其他构建产物（CSS、资源文件等）
|
||
|
||
### 自动排除的文件
|
||
|
||
打包脚本会自动排除以下文件：
|
||
- ❌ `.DS_Store` - macOS 系统文件
|
||
- ❌ `*.backup`, `*.bak` - 备份文件
|
||
- ❌ `*.tmp` - 临时文件
|
||
- ❌ `__MACOSX/` - macOS 压缩产物
|
||
- ❌ `.git/` - Git 版本控制文件
|
||
- ❌ `node_modules/` - 依赖文件
|
||
|
||
## 📊 打包信息
|
||
|
||
打包完成后，脚本会显示：
|
||
|
||
- ✅ 文件名称和路径
|
||
- ✅ 版本号
|
||
- ✅ 文件大小（压缩后）
|
||
- ✅ 文件质量评估（<5MB优秀）
|
||
|
||
## 🌐 上传到 Chrome Web Store
|
||
|
||
### 前提条件
|
||
|
||
1. **开发者账户**：注册 Chrome Web Store 开发者账户（$5 一次性费用）
|
||
2. **准备材料**：
|
||
- 扩展 ZIP 包（通过 `npm run package` 生成）
|
||
- 至少 1 张截图（1280x800 或 640x400）
|
||
- 详细描述和简短描述
|
||
- 隐私政策 URL（如果使用权限）
|
||
|
||
### 上传步骤
|
||
|
||
1. **访问开发者控制台**
|
||
```
|
||
https://chrome.google.com/webstore/devconsole
|
||
```
|
||
|
||
2. **创建新项**
|
||
- 点击"新增项"
|
||
- 上传生成的 ZIP 文件（`releases/ssp-v1.0.0.zip`）
|
||
|
||
3. **填写商店列表信息**
|
||
- 详细描述（推荐 800-1000 字）
|
||
- 简短描述（<132 字符）
|
||
- 上传截图（至少 1 张，推荐 3-5 张）
|
||
- 选择分类：生产力工具
|
||
|
||
4. **配置隐私设置**
|
||
- 说明权限用途
|
||
- 提供隐私政策链接
|
||
- 说明数据处理方式
|
||
|
||
5. **提交审核**
|
||
- 检查所有必填项
|
||
- 点击"提交审核"
|
||
- 等待审核结果（通常 24-48 小时）
|
||
|
||
## 🔄 版本更新流程
|
||
|
||
### 1. 更新版本号
|
||
|
||
在 `package.json` 中更新版本号：
|
||
|
||
```json
|
||
{
|
||
"version": "1.1.0"
|
||
}
|
||
```
|
||
|
||
建议同步更新 `public/manifest.json` 的版本号（虽然打包脚本会使用 package.json 的版本）。
|
||
|
||
### 2. 构建和打包
|
||
|
||
```bash
|
||
npm run package
|
||
```
|
||
|
||
### 3. 上传新版本
|
||
|
||
- 在 Chrome Web Store 开发者控制台
|
||
- 选择现有扩展
|
||
- 上传新的 ZIP 包
|
||
- 填写更新说明
|
||
- 提交审核
|
||
|
||
## 🛠️ 故障排查
|
||
|
||
### 问题：找不到 zip 命令
|
||
|
||
**错误信息**：
|
||
```
|
||
❌ 未找到系统zip命令
|
||
```
|
||
|
||
**解决方案**：
|
||
|
||
- **macOS**：已预装 zip，无需操作
|
||
- **Linux**：
|
||
```bash
|
||
sudo apt-get install zip
|
||
```
|
||
- **Windows**：
|
||
- 安装 [Git for Windows](https://git-scm.com/download/win)（包含 Git Bash）
|
||
- 或使用 [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install)
|
||
|
||
### 问题：dist 目录不存在
|
||
|
||
**错误信息**：
|
||
```
|
||
❌ dist目录不存在
|
||
请先运行构建命令：npm run build
|
||
```
|
||
|
||
**解决方案**：
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### 问题：文件大小过大
|
||
|
||
**警告信息**：
|
||
```
|
||
⚠️ ZIP文件超过10MB，可能影响审核速度
|
||
```
|
||
|
||
**优化建议**：
|
||
1. 检查是否包含不必要的资源文件
|
||
2. 压缩图片资源
|
||
3. 移除未使用的依赖
|
||
4. 使用 Vite 构建优化
|
||
|
||
### 问题：版本号格式无效
|
||
|
||
**错误信息**：
|
||
```
|
||
❌ 无效的版本号格式
|
||
```
|
||
|
||
**解决方案**：
|
||
确保 `package.json` 中的版本号遵循语义化版本规范（SemVer）：
|
||
- ✅ 正确：`1.0.0`, `1.2.3`, `2.0.0-beta.1`
|
||
- ❌ 错误：`v1.0`, `1.0`, `latest`
|
||
|
||
## 📝 最佳实践
|
||
|
||
### 1. 版本管理
|
||
|
||
- 遵循[语义化版本](https://semver.org/lang/zh-CN/)规范
|
||
- 主版本号（Major）：不兼容的 API 修改
|
||
- 次版本号（Minor）：向下兼容的功能新增
|
||
- 修订号（Patch）：向下兼容的问题修正
|
||
|
||
### 2. 发布前检查清单
|
||
|
||
- [ ] 运行所有测试：`npm test`
|
||
- [ ] 代码质量检查：`npm run lint`
|
||
- [ ] 类型检查：`npm run type-check`
|
||
- [ ] 本地功能测试（加载 dist 到浏览器）
|
||
- [ ] 更新版本号
|
||
- [ ] 更新 CHANGELOG.md
|
||
- [ ] 创建 Git 标签
|
||
|
||
### 3. Git 工作流
|
||
|
||
```bash
|
||
# 1. 更新版本号
|
||
npm version patch # 或 minor, major
|
||
|
||
# 2. 提交更改
|
||
git add .
|
||
git commit -m "chore: release v1.0.1"
|
||
|
||
# 3. 创建标签
|
||
git tag v1.0.1
|
||
|
||
# 4. 推送到远程
|
||
git push origin main --tags
|
||
|
||
# 5. 打包发布
|
||
npm run package
|
||
```
|
||
|
||
### 4. 保留历史版本
|
||
|
||
`releases/` 目录已在 `.gitignore` 中排除，但建议：
|
||
- 在本地保留最近 3-5 个版本的 ZIP 包
|
||
- 使用 GitHub Releases 存档重要版本
|
||
- 记录每个版本的发布日期和审核通过日期
|
||
|
||
## 🔗 相关资源
|
||
|
||
- [Chrome 扩展开发者文档](https://developer.chrome.com/docs/extensions/)
|
||
- [Chrome Web Store 政策](https://developer.chrome.com/docs/webstore/program_policies/)
|
||
- [发布检查清单](https://developer.chrome.com/docs/webstore/publish/)
|
||
- [语义化版本规范](https://semver.org/lang/zh-CN/)
|
||
|
||
## 💡 提示
|
||
|
||
- 首次发布审核可能需要更长时间（1-7 天）
|
||
- 后续更新通常更快（24-48 小时）
|
||
- 保持良好的代码质量和文档可以加速审核
|
||
- 及时响应审核人员的问题和反馈
|
||
|
||
---
|
||
|
||
**SearchSyntax Pro** - 让高级搜索变得简单易用
|