三端齐发：BewlyBewly浏览器扩展上架全流程与审核避坑指南
项目地址: https://gitcode.com/gh_mirrors/bew/BewlyBewly 你还在为浏览器扩展上架多平台而头疼？本文将系统梳理BewlyBewly项目从构建打包到Chrome、Firefox应用商店上架的完整流程，结合实战经验总结各平台审核要点，助你顺利通过审核。读完你将掌握：三端打包差异化配置、Manifest V3适配方案、应用商店素材准备清单、常见审核驳回案例及解决方案。
环境准备与构建配置
BewlyBewly采用TypeScript+Vue3技术栈，使用pnpm作为包管理器，通过vite和tsup实现构建流程。核心构建脚本定义在package.json中，提供了开发、构建、打包的完整命令链。
基础环境要求
- Node.js 18+ 与 pnpm 9.4.0+
- Chrome/Firefox 浏览器（用于测试）
- 应用商店开发者账号（Chrome Web Store需缴纳一次性费用，Firefox Add-ons免费）
关键构建命令解析
| 命令 | 功能描述 | 输出目录 |
|---|---|---|
pnpm dev | 开发模式（Chrome） | extension/ |
pnpm dev-firefox | 开发模式（Firefox） | extension-firefox/ |
pnpm build | 生产构建（Chrome） | extension/ |
pnpm build-firefox | 生产构建（Firefox） | extension-firefox/ |
pnpm pack | 生成发布包 | extension.zip / extension.xpi |
构建流程通过条件编译实现浏览器差异化处理，关键逻辑在scripts/manifest.ts中，根据isFirefox环境变量决定生成不同的manifest文件路径和内容。
Manifest配置与浏览器适配
扩展清单文件（manifest.json）是上架的核心文件，BewlyBewly通过src/manifest.ts动态生成适配Chrome和Firefox的配置，实现一套代码三端部署。
核心适配策略
- Manifest版本选择：采用V3标准，这是Chrome Web Store的强制要求，Firefox 109+也已支持V3
- 权限声明优化：
- Chrome：使用
declarativeNetRequestAPI实现网络请求拦截 - Firefox：因兼容性限制保留
webRequest权限组
- Chrome：使用
- 背景页处理：Chrome使用Service Worker，Firefox保留传统background scripts
关键配置代码示例
// 权限差异化配置（src/manifest.ts 第34-42行）
permissions: [
'tabs',
'storage',
'scripting',
'declarativeNetRequest',
...isFirefox
? ['webRequest', 'webRequestBlocking']
: [],
],
图1：构建输出目录结构对比，左侧为Chrome版本，右侧为Firefox版本
打包流程与发布包生成
打包流程通过npm scripts串联实现，核心逻辑在package.json的scripts部分，最终生成符合各应用商店要求的压缩包格式。
打包步骤分解
- 清理旧文件：通过rimraf清除历史构建产物
- 资源准备：执行scripts/prepare.ts处理静态资源
- 代码构建：
- 页面资源：vite构建Vue组件和样式
- 背景脚本：tsup打包TypeScript代码
- 内容脚本：vite单独构建content scripts
- 清单生成：scripts/manifest.ts根据环境生成适配的manifest.json
- 压缩打包：生成zip格式（Chrome）和xpi格式（Firefox）的发布包
发布包验证
打包完成后需验证以下内容：
- 文件结构完整性：确认所有必要资源包含在内
- manifest.json格式正确性：可使用Web Extensions Manifest Validator在线验证
- 扩展功能测试：通过
pnpm start:chromium或pnpm start:firefox命令测试打包后的扩展
应用商店上架流程
Chrome Web Store发布
-
准备材料：
- 扩展包：extension.zip（最大8MB）
- 图标：512x512px PNG（assets/icon-512.png）
- 截图：至少1张1280x800px截图，展示扩展核心功能
- 宣传图：1200x600px横幅图（可选）
-
上传流程：
- 登录Chrome开发者控制台
- 点击"添加新项"，上传ZIP包
- 填写商品详情（名称、描述、支持链接等）
- 设置发布范围（公开/受信任测试者）
- 提交审核（通常需要24-48小时）
Firefox Add-ons发布
-
准备材料：
- 扩展包：extension.xpi（通过
pnpm pack:xpi生成） - 源代码包：extension-firefox-sources.zip（通过
pnpm pack:zip-firefox-sources生成） - 图标与截图：要求与Chrome类似，但支持更多格式
- 扩展包：extension.xpi（通过
-
上传流程：
- 登录Firefox开发者中心
- 点击"提交新扩展"，上传XPI包
- 完成技术验证后填写元数据
- 上传源代码包（Firefox强制要求）
- 提交审核（通常需要1-3天）
图2：BewlyBewly扩展图标（512x512px），符合应用商店图标格式要求
审核常见问题与解决方案
权限声明问题
驳回案例：Chrome审核因"过度权限申请"被拒
解决方案：在manifest中移除未使用的webNavigation权限，仅保留必要权限。权限精简逻辑见src/manifest.ts第97-98行：
if (isDev)
manifest.permissions?.push('webNavigation')
仅在开发环境添加调试所需权限，生产环境自动剔除。
内容安全策略问题
驳回案例：Firefox审核提示CSP策略不安全
解决方案：严格限制script-src和object-src，生产环境配置见src/manifest.ts第77-81行：
content_security_policy: isFirefox
? {
extension_pages: 'script-src \'self\'; object-src \'self\'',
}
: {
extension_pages: isDev
? `script-src 'self' http://localhost:${port}; object-src 'self' http://localhost:${port}`
: 'script-src \'self\'; object-src \'self\'',
},
用户数据处理问题
驳回案例：因未提供隐私政策被拒
解决方案：在扩展描述中明确说明数据处理方式，并在README.md中添加隐私政策链接。BewlyBewly仅在本地存储用户偏好设置，不进行数据上传，相关实现见src/composables/useStorageLocal.ts。
发布后维护与版本更新
版本号管理
遵循语义化版本（SemVer）规范，版本号定义在package.json第5行："version": "0.24.0"。更新时需同步修改此值，构建系统会自动将版本号注入manifest.json。
更新流程
- 修改版本号并提交代码
- 执行
pnpm build && pnpm build-firefox && pnpm pack生成新发布包 - 登录各应用商店后台上传新版本
- 填写更新日志（需包含用户可见的功能变更）
统计分析集成
建议集成Web Store Stats或Firefox Telemetry了解用户使用情况，但需遵守各平台隐私政策。BewlyBewly采用本地分析方案，相关实现见src/stores/mainStore.ts。
总结与最佳实践
BewlyBewly的三端发布流程通过工程化手段实现了高效管理，核心经验包括：
- 构建流程自动化：通过npm scripts和条件编译减少人工操作
- manifest动态生成：解决Chrome与Firefox的API差异
- 权限最小化：仅声明必要权限，降低审核风险
- 材料规范化：统一管理应用商店所需的图标、截图等素材
建议建立发布检查清单，包含以下要点：
- 版本号已递增
- 测试所有浏览器兼容性
- 生产构建已禁用调试功能
- 隐私政策已更新
- 截图和宣传材料符合最新界面
随着浏览器扩展生态的不断发展，需持续关注Manifest规范更新和各平台政策变化。BewlyBewly项目将继续优化发布流程，相关工具脚本将在scripts/目录下持续迭代。
点赞+收藏+关注，获取更多扩展开发与上架实战经验。下期预告：《BewlyBewly插件国际化实现：多语言架构设计与本地化工作流》。项目完整代码可通过git clone https://gitcode.com/gh_mirrors/bew/BewlyBewly获取。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
