开发流程

日常开发、文档部署、版本发布三条流程的总规范。

总览

本地开发 ──push──▶ dev（日常开发分支：组件开发 / 优化 / 文档迭代）
                      │ ① 功能稳定，需要部署文档：git merge --no-ff dev
                      ▼
                   master（集成与发布分支 = EdgeOne 文档生产分支）
                      │ ② 文档部署：push master → EdgeOne 自动/手动构建上线
                      │ ③ 版本发布：npm run release
                      ▼
                   release（版本提交 + 附注 tag vX.Y.Z）
                      ├─④ npm publish → 官方源（npmjs.com）
                      └─⑤ 自动合回 master 并 push
                             └─⑥ 手动回同步 dev（merge --ff-only master）

分支	职责	谁往里写
feat/*、fix/*	单组件/单任务短命分支（可选）	直接提交
dev	日常开发集成分支，90% 时间在这里	直接提交 + 合并 feat 分支
master	集成与发布分支，EdgeOne 文档生产分支	只接受 dev 合并（--no-ff）与 release 版本提交
release	版本号提交 + tag，由发布脚本自动管理	仅脚本

一、日常开发（在 dev 上）

git checkout dev
git pull

# 开发组件 / 优化 / 文档...
#   新增组件的三步规范见仓库 README（组件目录 / 注册 / 文档与 demo）

npm run typecheck        # 合并前质量门：类型检查必须零错误
npm run docs:build       # 涉及文档/demo 变更时，本地验证文档站构建
npm run docs:preview     # 本地预览 http://127.0.0.1:4173 核对效果

git add -A
git commit -m "feat(biz-xxx): 新增 xxx 组件"
git push origin dev

大型改动建议先切功能分支，完成再合回：

git checkout -b feat/biz-xxx dev
# ...开发...
git checkout dev && git merge --no-ff feat/biz-xxx

二、文档部署流程（dev → master → EdgeOne）

1. 合并到 master：

git checkout master && git pull
git merge --no-ff dev -m "merge: dev -> master（部署文档）"
git push origin master

2. 触发 EdgeOne 构建（生产分支 = master）：

• 自动触发：push 到 master 由 Git 集成 / Webhook 自动构建（若 Gitee → EdgeOne 的 webhook 触发链未配通，先按下方「部署触发链」检查）；
• 手动触发：EdgeOne 控制台 → 项目 → 部署 → 选择 master 分支开始部署（也可用 「项目设置 → 部署钩子」生成的 URL 发起 POST 触发）。

3. 验证上线：

curl -s -o /dev/null -w "%{http_code}" https://vue3-ep-biz-lib.edgeone.dev/   # 期望 200

4. 回同步 dev（保持两条分支不漂移）：

git checkout dev && git merge --ff-only master && git push origin dev

EdgeOne 关键事实（排障前先看）：

事实	说明
生产域名	https://vue3-ep-biz-lib.edgeone.dev/（域名管理中的项目域名，指向最新生产部署）
预览链接	每次部署另生成带 eo_token 的预览链接，3 小时时效，仅用于临时核对
构建配置	仓库根 edgeone.json（npm run docs:build → docs/.vitepress/dist，Node 20.18.0）
部署触发链	Gitee 仓库需配置指向 EdgeOne 部署钩子的 Webhook（管理 → WebHooks → Push 事件）；未配通时用控制台手动部署
大陆访问	默认域名对大陆网络有合规令牌限制（401），公开访问需绑定自定义域名（免备案区域）或调整加速区域——待决策事项
构建产物保留	仅最近 3 次成功部署的产物可访问，更早的返回 401，可"重新部署"恢复

三、版本发布流程（master 上，一条命令）

npm run release              # 默认 patch；-- minor / -- major / -- x.y.z

脚本自动完成（详见发布指南）：

步骤	动作
0	前置校验：工作树干净 / 官方源连通 / 凭据就绪 / 版本未占用 / dev 未合并提交提醒
1	切换或新建 release 分支，ff 合入 master 最新提交
2	版本号递增 + chore(release): vX.Y.Z 提交 + 附注 tag
3	typecheck → build（产物永远来自当前源码）
4	npm pack --dry-run 包内容预览 → 人工确认（y/N）
5	npm publish → 官方源（granular token 凭据，免 OTP）
6	push release + tag → master 快进合回并 push（顺带触发文档部署）
7	官方源验证（读副本延迟自动重试）

发布后同样回同步 dev：git checkout dev && git merge --ff-only master && git push origin dev。

四、分支与提交规范

提交信息（Conventional Commits）：

前缀	用途
feat(组件名)	新组件 / 功能扩展
fix(组件名)	缺陷修复
docs	文档与 demo
chore	工程 / 构建 / 依赖
chore(release)	版本提交（脚本专用）

纪律守则：

1. 不在 master 上直接开发——所有改动经 dev 流入（发布脚本的版本提交除外）；
2. master 只进合并——git merge --no-ff dev 保留集成点，可追溯"哪批功能一起上线"；
3. 合并前过质量门——npm run typecheck 零错误；涉及文档再过 npm run docs:build；
4. 发布/部署后回同步——merge --ff-only master 回 dev，避免下次合并非快进；
5. 可选加固——Gitee 仓库 → 管理 → 分支保护：master 设为保护分支（禁 force push、仅合并进入）。