Read [](file:///opt/cyy/code-docs)

Read [](file:///opt/cyy/code-docs/package.json)

Read [](file:///opt/cyy/code-docs/docusaurus.config.js#1-1), lines 1 to 120

Read [](file:///opt/cyy/code-docs/sidebars.js)

Read [](file:///opt/cyy/code-docs/src/components/HomepageFeatures.js#1-1), lines 1 to 50

Read [](file:///opt/cyy/code-docs/src/pages/index.js)

Read [](file:///opt/cyy/code-docs/babel.config.js)

Read [](file:///opt/cyy/code-docs/.github)

Read [](file:///opt/cyy/code-docs/docs/intro-docs.md#1-1), lines 1 to 40

Read [](file:///opt/cyy/code-docs/.github/workflows)

Read [](file:///opt/cyy/code-docs/docs/LeetCode/CodingInterviews/StackAndQueue/MaxValueOfQueue.md#1-1), lines 1 to 50

Read [](file:///opt/cyy/code-docs/.github/workflows/nodejs.yml)

Read [](file:///opt/cyy/code-docs/docs/LeetCode/CodingInterviews/StackAndQueue/%E4%BA%8C%E5%8F%89%E6%A0%91%E7%9A%84%E9%81%8D%E5%8E%86.md#1-1), lines 1 to 30

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:  

Read [](file:///opt/cyy/code-docs/blog/2021-04-26-use-code-docs.md)

Read [](file:///opt/cyy/code-docs/src/css/custom.css)

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 混用 | 🟠 高 |

---

## 二、问题点清单

**严重问题：**
1. `@docusaurus/core: 2.0.0-alpha.73` — 当前稳定版为 `3.7.x`，跨越近3年迭代，含大量Breaking Changes
2. Node.js 12 已于2022年4月正式 EOL，CI/CD 中仍在使用
3. Algolia `apiKey` 明文暴露在 docusaurus.config.js
4. `remark-math@3` + `rehype-katex@4` 与 Docusaurus 3.x 使用的 MDX 3.x 不兼容
5. .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` 的英文占位内容替换为项目实际特性：
```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 以减少维护成本。

---

## 升级注意事项

1. **Breaking Change 重点**：Docusaurus 3.x 使用 MDX 3，对 `{}` 中的 HTML 实体、未闭合标签更严格，升级后需逐一检测现有 `.md`/`.mdx` 文件：
   ```bash
   npx docusaurus-mdx-checker
   ```

2. **KaTeX 配置变更**：`remark-math` v6+ 和 `rehype-katex` v7+ 的引入方式从 `require()` 改为 ES Module `import`，`docusaurus.config.ts` 需同步调整

3. **React 18 并发模式**：`ReactDOM.render` 已废弃，检查是否有自定义入口文件使用旧 API

4. **升级顺序建议**：
   ```
   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` 分支触发部署
- [ ] 无硬编码密钥在代码仓库中