跳到主要内容

Git代码更新注意事项

基本更新流程​

1. 添加更改​

git add .

将所有更改添加到暂存区。如需添加特定文件，可使用 git add 文件名。

2. 提交更改​

git commit -m "更新网页内容"

提交信息应简洁明了地描述本次更改内容。

3. 拉取远程更新​

git pull

重要：在推送前先拉取远程更改，避免冲突。

如出现编辑器要求输入合并信息，可直接保存默认信息（在Vim中按 :wq）。

4. 推送到远程仓库​

git push

将本地提交推送到远程仓库。

Docusaurus网站更新流程​

1. 本地预览​

npm run start

在本地运行网站进行预览，确认更改效果。

2. 构建静态文件​

npm run build

生成静态网站文件用于部署。

3. 部署网站​

npm run deploy

将网站部署到托管服务（如GitHub Pages）。

部署之前需要先绑定你的github用户名

set GIT_USER=你的GitHub用户名

常见问题及解决方案​

推送被拒绝​

! [rejected] main -> main (fetch first)

解决方法：

  1. 先执行 git pull 拉取远程更改
  2. 解决可能的冲突
  3. 再执行 git push

路径问题处理​

将 \test_website\ 改为 \ 的路径修正​

在以下情况需要注意路径问题：

  1. 配置文件修改：

    • 在 docusaurus.config.js 中检查 baseUrl 设置
    // 错误配置
    baseUrl: '/test_website/',

    // 正确配置（如果部署到根目录）
    baseUrl: '/',

  2. 资源引用路径：

    • 在Markdown文件中引用图片或其他资源时：
    <!-- 错误引用 -->
    ![描述](/test_website/img/example.png)

    <!-- 正确引用 -->
    ![描述](/img/example.png)

  3. 内部链接修正：

    <!-- 错误链接 -->
    [链接文字](/test_website/docs/某文档)

    <!-- 正确链接 -->
    [链接文字](/docs/某文档)

  4. 部署配置：

    • 如果使用 gh-pages，检查 package.json 中的部署脚本：
    "scripts": {
      "deploy": "docusaurus deploy"
    }

  5. 路径问题导致的构建错误：

    • 如果出现 Image not found 错误，检查文件路径是否包含多余的 /test_website/ 前缀

注意：路径修改后必须重新构建项目才能看到效果。先运行 npm run build 检查是否有路径错误。

检查分支状态​

git status   # 查看当前状态
git branch   # 查看本地分支
git branch -a  # 查看所有分支（包括远程）

构建失败 - 资源缺失​

如遇到类似 Image not found 错误：

  1. 确保所有引用的资源文件（如图片）都已添加到正确位置
  2. 检查文件名大小写是否一致（某些系统区分大小写）
  3. 检查路径是否正确，避免使用错误的 /test_website/ 前缀

无法链接443​

如遇到类似 Could not connect to server 错误：

  1. 让git走代理，如果你本地有代理软件（Clash / V2Ray / SSR），假设监听在 127.0.0.1:7890

    git config --global http.proxy http://127.0.0.1:7890
    git config --global https.proxy http://127.0.0.1:7890

  2. 测试

    git ls-remote https://github.com/你的用户名/项目名称

  3. 能正常输出就说明打通了，接下来继续执行部署

最佳实践​

  1. 频繁提交：小步提交更容易追踪变化
  2. 良好的提交信息：简洁描述修改内容
  3. 先拉取后推送：始终先执行 git pull 再 git push
  4. 本地测试：在推送前进行本地测试
  5. 备份重要文件：进行大量更改前备份重要文件
  6. 路径一致性：保持项目中的路径引用一致，避免混用 /test_website/ 和 / 前缀

团队协作注意事项​

  1. 避免直接在主分支（main/master）上工作
  2. 使用特性分支（feature branches）开发新功能
  3. 通过拉取请求（Pull Request）合并更改
  4. 保持良好的沟通，及时同步进度
  5. 统一路径引用规范，避免路径不一致导致的问题