280 lines
10 KiB
Markdown
280 lines
10 KiB
Markdown
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` 分支触发部署
|
||
- [ ] 无硬编码密钥在代码仓库中
|