10 KiB
Let me check for the garbled files:
Ran terminal command: find /opt/cyy/code-docs -maxdepth 1 -type f | sort && echo "---" && ls -la /opt/cyy/code-docs/ | head -30
Found them. Both are empty files (size 0) with garbled names. Let me delete them:
Ran terminal command: cd /opt/cyy/code-docs && find . -maxdepth 1 -name "2p" -delete && find . -maxdepth 1 -name $',\xef\xbf\xbd0p>' -delete 2>/dev/null; find . -maxdepth 1 -type f -size 0 ! -name "." | head -20
Ran terminal command: cd /opt/cyy/code-docs && ls -la | grep "^-rw.* 0 " | awk '{print $NF}' && find . -maxdepth 1 -type f -size 0 -exec rm -v {} ;
Ran terminal command: cd /opt/cyy/code-docs && find . -maxdepth 1 -type f -size 0 | wc -l && ls | head -20
Both garbled files removed. Now let me read the remaining docs for the full analysis:
Now I have a complete picture. Let me compose the professional analysis and upgrade prompt:
两个乱码文件处理完毕
已删除根目录下的两个空白乱码文件：
2p（空文件）,°0p>;°8p>...Rich2p>PEd...（空文件，名称为二进制乱码）
项目分析报告 + 系统升级提示词
一、项目现状分析
| 维度 | 当前状态 | 风险等级 |
|---|---|---|
| Docusaurus 版本 | 2.0.0-alpha.73 (2021年) |
🔴 极高 |
| React 版本 | 17.0.1 |
🟠 高 |
| Node.js (CI) | 12 (EOL) |
🔴 极高 |
| 部署方式 | FTP 明文传输 | 🔴 安全风险 |
| Algolia Key | 硬编码在公开配置文件 | 🔴 信息泄露 |
| TypeScript | 未使用 | 🟡 中 |
| 包管理器 | yarn.lock + package-lock.json 混用 | 🟠 高 |
二、问题点清单
严重问题：
@docusaurus/core: 2.0.0-alpha.73— 当前稳定版为3.7.x，跨越近3年迭代，含大量Breaking Changes- Node.js 12 已于2022年4月正式 EOL，CI/CD 中仍在使用
- Algolia
apiKey明文暴露在 docusaurus.config.js remark-math@3+rehype-katex@4与 Docusaurus 3.x 使用的 MDX 3.x 不兼容- .DS_Store 文件未被 .gitignore 过滤，已提交到仓库
架构问题：
6. 纯 JavaScript 项目，Docusaurus 3.x 全面支持 TypeScript，缺失类型安全
7. FTP 部署方案无加密、无回滚、无原子发布能力
8. GitHub Actions 使用过期版本：actions/checkout@v2.3.2、actions/setup-node@v2-beta
9. yarn.lock 和 package-lock.json 同时存在，包管理器冲突
10. CI 无分支过滤，每次 push（包括草稿分支）都会触发生产部署
内容问题：
11. HomepageFeatures.js 仍为 Docusaurus 默认英文占位内容
12. 依赖外部图片 CDN（s3.ax1x.com、z3.ax1x.com）存在链接失效风险
13. i18n 配置了 en/zh-cn 双语，但无对应翻译文件
14. Blog 文章内含硬编码域名链接 http://docs.yaoyuan.io/...
15. Tutorial 目录仍为 Docusaurus 官方示例内容，未替换为项目自有文档
三、系统升级提示词（可直接用于 AI 对话）
你是一名资深全栈工程师，精通 Docusaurus、React、GitHub Actions 和技术文档工程。
我需要你对下述项目进行全面系统升级，请严格按照优先级顺序执行，给出完整可执行的代码和配置。
## 项目背景
- 项目名称：code-docs（CodeDocs 编程文档站）
- 当前框架：Docusaurus v2.0.0-alpha.73（React 17，纯 JS）
- 内容：中文技术文档，包含 LeetCode、Spring Boot、Spring Cloud、React、Vue 专题
- 部署：GitHub Actions → FTP → 自托管服务器（http://docs.yaoyuan.io）
---
## 升级任务列表（按优先级排序）
### P0 - 核心框架升级
**1. 升级 Docusaurus 3.x**
- 将 `@docusaurus/core` 和 `@docusaurus/preset-classic` 从 `2.0.0-alpha.73` 升级到最新稳定版 `^3.7.0`
- 同步升级所有 peer dependencies：`react@^18.3`、`react-dom@^18.3`
- 迁移 `docusaurus.config.js` 为 `docusaurus.config.ts`（TypeScript 配置）
- 替换已废弃 API：
- `module.exports` → `export default` (ESM)
- `DocusaurusConfig` 类型导入路径变更
- `themeConfig.algolia` 结构校验更新
- 更新 MDX 依赖以兼容 MDX 3.x：
- `remark-math` 升级到 `^6.0`，`rehype-katex` 升级到 `^7.0`
- 检查所有使用 MDX JSX 语法的 `.md` 文件（如 `docs/intro-docs.md` 中的 `<Tabs>`），确保兼容 MDX 3 严格模式
**2. 升级 TypeScript 支持**
- 初始化 `tsconfig.json`（继承 `@docusaurus/tsconfig`）
- 将 `src/` 目录下所有 `.js`/`.jsx` 文件迁移为 `.ts`/`.tsx`
- 为 `HomepageFeatures`、`index` 页面添加完整 Props 类型声明
- 升级 `babel.config.js` → `babel.config.ts`
---
### P1 - 安全修复
**3. 消除 Algolia Key 泄露风险**
- 将 `docusaurus.config` 中硬编码的 Algolia `apiKey`、`appId` 提取到环境变量
- 创建 `.env.local` 文件（加入 `.gitignore`）：
ALGOLIA_APP_ID=D8PEAPGLZ3 ALGOLIA_API_KEY=<your_search_only_api_key>
- 在配置中使用 `process.env.ALGOLIA_APP_ID` 引用
- 在 GitHub Actions 中添加对应 `secrets`
**4. 修复 `.gitignore`**
添加以下条目：
.DS_Store .env.local .env.*.local
---
### P2 - CI/CD 现代化
**5. 重写 GitHub Actions 工作流**
```yaml
# .github/workflows/deploy.yml
name: Deploy to Production
on:
push:
branches: [main] # 仅 main 分支触发，移除草稿分支误部署
pull_request:
branches: [main] # PR 仅做构建校验，不部署
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4 # 升级到 v4
- uses: actions/setup-node@v4 # 升级到 v4
with:
node-version: '20' # Node 20 LTS
cache: 'npm' # 启用依赖缓存
- name: Install dependencies
run: npm ci # 使用 ci 替代 install，更稳定
- name: Build
run: npm run build
env:
ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
deploy:
needs: build
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
steps:
# 推荐迁移至 GitHub Pages 或 SSH 部署，若保留 FTP 则升级：
- uses: SamKirkland/FTP-Deploy-Action@v4.3.5
with:
server: ${{ secrets.FTP_SERVER }}
username: ${{ secrets.FTP_USER }}
password: ${{ secrets.FTP_PWD }}
local-dir: ./build/
server-dir: code-docs/www/
架构建议：将 FTP 部署迁移至 GitHub Pages（零成本）或 Vercel（自动预览 PR），消除明文传输风险。
P3 - 内容与架构优化
6. 首页本地化改造
将 src/components/HomepageFeatures.tsx 的英文占位内容替换为项目实际特性：
const FeatureList: FeatureItem[] = [
{
title: '📚 系统化文档',
description: '涵盖后端（Spring Boot/Cloud）、前端（React/Vue）和算法（LeetCode），分门别类，清晰索引。',
},
{
title: '⚡ 快速检索',
description: '集成 Algolia DocSearch，毫秒级全文检索，快速定位任意知识点。',
},
{
title: '🌐 持续更新',
description: '由技术团队持续维护，定期同步最新技术栈实践和面试题解析。',
},
];
移除对 undraw_docusaurus_*.svg 的依赖（这些文件在 img 中可能不存在）。
7. 清理默认内容
- 删除 tutorial-basics 和 tutorial-extras 目录（Docusaurus 默认示例，与项目无关）
- 删除 2021-01-01-hello-world.md 和 2021-01-01-hola.md（官方示例博客）
- 统一 Blog 文章中的链接为相对路径，移除硬编码域名
8. 图片资源本地化
将外部 CDN 图片（s3.ax1x.com、z3.ax1x.com）下载到 img 目录，
替换为相对路径引用，避免 CDN 失效导致图片断链。
9. 统一包管理器
删除 package-lock.json（保留 yarn.lock），或删除 yarn.lock（保留 npm），
在 package.json 中声明 "packageManager": "npm@10.x.x" 或 "yarn@4.x.x" 固定版本。
10. 完善 i18n（可选）
当前 docusaurus.config 配置了 zh-cn + en 双语，但缺少翻译文件。
执行 npm run write-translations 生成翻译模板，或移除 en locale 以减少维护成本。
升级注意事项
-
Breaking Change 重点：Docusaurus 3.x 使用 MDX 3，对
{}中的 HTML 实体、未闭合标签更严格，升级后需逐一检测现有.md/.mdx文件：npx docusaurus-mdx-checker -
KaTeX 配置变更：
remark-mathv6+ 和rehype-katexv7+ 的引入方式从require()改为 ES Moduleimport，docusaurus.config.ts需同步调整 -
React 18 并发模式：
ReactDOM.render已废弃，检查是否有自定义入口文件使用旧 API -
升级顺序建议：
Step 1: 先在新分支 feat/upgrade-v3 上操作 Step 2: 升级依赖 → Step 3: 修复 MDX 兼容性 → Step 4: 本地构建验证 Step 5: 修复 CI/CD → Step 6: 合并到 main 触发部署
升级后验证清单
npm run build零报错、零警告npm run start本地预览正常- 中文搜索正常（Algolia）
- KaTeX 数学公式正常渲染
- 深色模式外观正常
- GitHub Actions 仅
main分支触发部署 - 无硬编码密钥在代码仓库中