.github/workflows/validate-and-build.yml

name: 验证与构建on: push: branches: [ main, develop ] pull_request: branches: [ main ]jobs: validate: runs-on: ubuntu-latest steps:uses: actions/checkout@v3name: 设置Node.js环境 uses: actions/setup-node@v3 with: node-version: '18' cache: 'npm'name: 安装依赖 run: npm ciname: 运行ESLint检查 run: npm run lintname: 运行Markdown格式检查 run: npm run lint:mdname: 验证文章元数据 run: npm run validate:articlesname: 检查术语库一致性 run: npm run validate:glossaryname: 验证分类体系 run: npm run validate:categories build: needs: validate runs-on: ubuntu-latest steps:uses: actions/checkout@v3name: 设置Node.js环境 uses: actions/setup-node@v3 with: node-version: '18' cache: 'npm'name: 安装依赖 run: npm ciname: 构建HTML静态文件 run: npm run build:htmlname: 生成PDF文档 run: npm run build:pdfname: 上传构建产物 uses: actions/upload-artifact@v3 with: name: build-artifactspath: dist/ reports/ ### 8.2 发布工作流 .github/workflows/publish.ymlname: 发布部署on: push: tags:'v*'jobs: publish: runs-on: ubuntu-latest steps:uses: actions/checkout@v3name: 设置Node.js环境 uses: actions/setup-node@v3 with: node-version: '18'name: 安装依赖 run: npm ciname: 构建生产版本run: npm run build:html npm run build:pdf npm run generate:indexname: 部署到GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist cname: tech-docs.example.com ## 9. 发布目录策略 ### 9.1 目录结构设计 dist/├── html/ # HTML版本│ ├── 计算机硬件/│ │ ├── 处理器/│ │ ├── 存储/│ │ └── 显卡/│ └── 计算机软件/│ ├── 操作系统/│ └── 数据库/├── docs/ # 文档版本│ ├── 计算机硬件/│ └── 计算机软件/├── pdf/ # PDF版本│ ├── single/ # 单篇文章│ └── collection/ # 合集版本├── reports/ # 质量报告│ ├── validation/│ ├── audit/│ └── statistics/└── index.html # 总索引页面 ### 9.2 文件命名规范 interface FileNamingConvention { // 基础格式: {分类}-{子分类}-{产品型号}-{文档类型}.html pattern: `${category}-${subcategory}-${product}-${type}.${format}`; // 示例 examples: [ "计算机硬件-处理器-Intel-Core-i9-13900K-架构分析.html", "计算机硬件-显卡-NVIDIA-RTX-4090-性能评测.html", "计算机软件-操作系统-Linux-Kernel-6.12-IO调度分析.html" ]; // 约束规则 rules: { category: '必须为一级分类', subcategory: '必须为二级分类', product: '产品型号或技术名称',type: '文档类型：性能评测架构分析白皮书等', maxLength: 200 }} ## 10. 术语库维护 ### 10.1 术语库结构 { "version": "1.0.0", "lastUpdated": "2025-12-02", "categories": { "计算机硬件": { "处理器": { "terms": { "Intel Core i9-13900K": { "definition": "Intel第13代酷睿i9系列旗舰处理器", "category": "处理器/Intel/第13代", "synonyms": ["i9-13900K", "Raptor Lake i9"], "validation": "\\bi9-?13900K\\b", "usage": "首次出现需用全称，后续可用缩写" } } } } }} ### 10.2 术语同步脚本 #!/bin/bashscripts/sync-glossary.shecho "同步术语库..."从CSV文件同步到JSONnode scripts/convert-glossary.js \ --input=config/术语库.csv \ --output=config/glossary.json \ --format=json验证术语一致性node scripts/validate-glossary.js \ --glossary=config/glossary.json \ --articles=docs/生成分类映射node scripts/generate-taxonomy.js \ --glossary=config/glossary.json \ --output=taxonomy/categories.jsonecho "术语库同步完成" ## 11. 故障排查指南 ### 11.1 常见错误及解决方案 | 错误类型 | 症状 | 原因 | 解决方案 | |----------|------|------|----------| | 元数据验证失败 | 构建时报"Invalid metadata"错误 | 标题格式不符合规范 | 检查三级分类格式，确保使用连字符分隔 | | 术语不匹配 | 文章中术语标红 | 术语库未更新 | 运行`npm run sync:glossary`同步术语库 | | 图片路径错误 | 图片无法显示 | 相对路径错误 | 使用绝对路径或确保图片在`public/images/`目录 | | PDF生成失败 | puppeteer超时 | 内存不足或网络问题 | 增加超时时间，检查系统资源 | | 分类层级错误 | 文章无法归档 | category字段格式错误 | 确保使用`/`分隔的三级分类格式 | ### 11.2 诊断工具 快速诊断npm run doctor验证所有配置npm run validate:config检查文章完整性npm run validate:articles -- --detailed生成系统报告npm run report:system清理缓存npm run clean ### 11.3 日志分析 // 日志级别配置const logLevels = { error: 0, warn: 1, info: 2, debug: 3, trace: 4};// 常见日志位置const logFiles = { build: 'logs/build.log', validation: 'logs/validation.log', publish: 'logs/publish.log', system: 'logs/system.log'}; ## 12. 可执行步骤与文件位置 ### 12.1 初始化项目 1. 克隆项目git clone <repository-url>cd tech-article-publishing-system2. 安装依赖npm install3. 配置环境变量cp .env.example .env编辑.env文件，配置Supabase连接信息4. 初始化数据库npm run db:migrate5. 同步术语库npm run sync:glossary ### 12.2 关键文件位置 ├── 配置文件│ ├── config/glossary.json # 术语库主文件│ ├── config/categories.yaml # 分类配置│ ├── config/terms.yaml # 术语定义│ └── .markdownlint.json # Markdown格式规则├── 脚本文件│ ├── scripts/validate.js # 文章验证脚本│ ├── scripts/build-html.js # HTML构建脚本│ ├── scripts/build-pdf.js # PDF生成脚本│ └── scripts/sync-glossary.js # 术语库同步├── 工作流文件│ ├── .github/workflows/ci.yml # 持续集成│ ├── .github/workflows/publish.yml # 发布部署│ └── .github/CODEOWNERS # 代码审查责任人└── 输出目录 ├── dist/html/ # HTML输出 ├── dist/pdf/ # PDF输出 └── reports/ # 质量报告 ### 12.3 日常维护命令 开发模式npm run dev # 启动开发服务器npm run lint # 代码格式检查npm run validate # 验证文章质量构建发布npm run build # 构建所有格式npm run build:html # 仅构建HTMLnpm run build:pdf # 仅构建PDFnpm run publish # 发布到生产环境维护管理npm run sync:glossary # 同步术语库npm run update:taxonomy # 更新分类体系npm run clean # 清理构建缓存npm run report # 生成质量报告