CodeGeex自动生成前端项目README部署文档指南

前端开发者常遇到项目写完却不想写README部署说明的难题。手动填写构建命令、环境变量、Nginx路径和HTTPS适配细节，容易遗漏且格式难以统一。不同部署环境（Docker、Nginx、Vercel）需要不同描述，更是令人头疼。

现在，插件、Web端和CLI三种工具均可自动生成包含这些内容的完整部署章节。插件通过解析package.json识别构建脚本；Web端支持模板锁定与Docker、HTTPS配置增强；CLI工具则灵活地追加或覆盖现有部署模块。

下面逐一演示具体用法。

VS Code 插件自动生成含部署章节的完整 README

此方法适用于已在VS Code中打开项目根目录的场景。确保项目包含package.json或vite.config.ts等构建配置文件，插件据此推断打包脚本和服务端口。

第一步： 确认工作区为项目根目录，且必须包含【package.json】文件。缺少该文件，插件无法识别构建与预览命令，后续流程无法进行。

第二步： 按下快捷键（Windows/Linux: Ctrl+Shift+P，Mac: Cmd+Shift+P）打开命令面板，输入并运行“CodeGeeX: Generate README”。

第三步： 等待约十秒，插件自动生成README.md并打开。立即检查文档末尾是否存在“## 部署说明”章节。若缺失，说明项目package.json中缺少scripts.build或scripts.preview字段，需补充后重试。

第四步： 找到“## 部署说明”下的子章节，确认包含“本地构建”、“Nginx静态托管”和“环境变量注入”三部分。尤其注意Nginx配置块需包含location / { root /var/www/my-app; try_files $uri $uri/ /index.html; }路由回退逻辑——这是单页应用部署的常见陷阱。

Web端上传压缩包定制部署章节

若需为多个前端项目生成风格统一的部署说明，并强制加入Docker流程，Web端比插件更可控。其模板锁定与字段增强功能显著提升效率。

方法一： 访问CodeGeeX官网文档生成页，点击“上传项目”，选择项目压缩包（如frontend-v2.3.zip）。注意：压缩包顶层目录应为项目名，避免嵌套父文件夹导致解析错误。上传后，在模板下拉框选择“Frontend Deployment Ready”。

方法二： 上传完成后，在“增强选项”中勾选“生成Dockerfile说明”和“添加Nginx HTTPS重定向配置”。确认后点击“开始生成”，下载生成的README.md。

若项目使用Vite + SSR模式，Web端自动识别server.mjs或entry-server.js，并在部署章节插入启动命令：node -r dotenv/config server.mjs dotenv_config_path=.env.production。免去手动查找补充的麻烦。

CLI工具注入独立部署模块

此方法适合将部署说明作为可复用模块嵌入已有README。仅追加结构化区块，不覆盖原有内容，尤其适合CI流程自动更新部署信息。

1、 在终端进入项目根目录，执行：
codegeex readme --section deployment --lang zh --template frontend-nginx

2、 命令执行后，在README.md底部新增“## 部署说明”章节，内容遵循Nginx最佳实践。包含upstream定义、gzip压缩启用、CSP头建议值，以及针对/assets/路径的expires 1y配置。

3、 如需切换为Docker部署模板，只需将参数改为--template frontend-docker。生成内容立即替换为Dockerfile构建步骤、multi-stage构建说明及docker-compose.yml示例。

4、 默认行为：若项目已存在“## 部署说明”章节，CLI将跳过。如需覆盖，必须显式添加【--force-section】参数，否则保留原有内容。