03 | 本地开发工作流

拥有流畅的工作流程能显著提升生产力与协作效率。工具本身并不复杂，关键在于把它们串成一条一致的链路：VS Code 负责本地开发与调试，Git 负责版本管理，GitHub 负责仓库托管与协作。

本文将介绍本地环境对齐、常用 VS Code 插件、Python venv 与 VS Code 的配合、unittest 测试流程、Git 的核心概念与常用命令，以及 GitHub 的项目发布与开源协作（含 Fork/PR），并演示如何在 VS Code 中配合 Codex 插件完成一次开发与修改。目标是把日常开发从“能写能跑”提升到“环境一致、改动可控、协作顺滑、问题可回溯”，为后续 Vibe Coding 与 SDD（规范驱动开发）打好基础。

VS Code：本地开发工作台

Visual Studio Code 是微软推出的免费开源代码编辑器，轻量级却功能强大，支持多种语言和扩展。它不仅是代码编辑器，更是本地开发工作台，可以集成终端、调试器、版本控制和扩展插件，帮助开发者在本地环境中高效编写、测试和调试代码。你可以从官方网站下载：VS Code 下载链接。

安装 VS Code

1. 从官方网站 code.visualstudio.com 下载并安装 VS Code。它支持 Windows、macOS 和 Linux。
2. 安装完成后，打开 VS Code，熟悉界面：侧边栏用于文件浏览、编辑器面板，以及集成终端（通过 Ctrl+ 或 Mac 上 Cmd+ 访问）。作为工作台，你可以在这里打开项目文件夹（File > Open Folder），并使用内置的 Git 支持和插件来管理整个开发流程。

常用 VS Code 插件

插件可以增强 VS Code 的功能。以下是一些开发者必备插件：

• Python（由 Microsoft 提供）：为 Python 开发提供 IntelliSense、智能调试、代码检查和 Jupyter 支持。
• GitLens（由 GitKraken 提供）：增强 Git 集成，包括 blame 注解、提交历史和分支比较，直接在编辑器中操作。
• Prettier（由 Prettier 提供）：意见性的代码格式化工具，确保代码库样式一致。
• Live Server（由 Ritwick Dey 提供）：为 Web 项目启动本地开发服务器，支持实时重载。
• Docker（由 Microsoft 提供）：从 VS Code 中管理 Docker 容器和镜像。
• Remote - SSH（由 Microsoft 提供）：通过 SSH 编辑远程服务器上的文件，非常适合跨机器对齐环境。
• Codex（由 OpenAI 提供）：这是一个基于 AI 的代码助手插件，利用 OpenAI 的 Codex 模型，可以自动生成代码建议、解释代码、修复 bug 等。安装后，它会像智能提示一样工作，例如在编写函数时输入注释，它就能生成完整代码。要使用它，需要 OpenAI 账户并启用（插件市场搜索 "Codex" 或 "openai.codex" 并安装）。官网链接：OpenAI Codex。

要安装插件，打开扩展视图（Ctrl+Shift+X 或 Mac 上 Cmd+Shift+X），搜索名称并点击安装。

对齐本地开发环境

为了确保团队成员或不同机器之间的一致性：

• 在项目根目录中使用 .vscode 文件夹存储工作区设置，例如推荐插件或调试配置（在 settings.json 和 extensions.json 中）。
• 通过 GitHub 同步设置：在 VS Code 中安装“Settings Sync”插件，并链接到 GitHub Gist。
• 对于跨平台一致性，避免在脚本中使用特定于操作系统的路径，并使用环境变量。作为本地工作台，VS Code 可以一键运行任务（如构建或测试），通过 Tasks.json 配置自定义命令。

设置 Python 虚拟环境（venv）

虚拟环境可以隔离项目依赖，避免不同项目之间的冲突。Python 内置的 venv 模块简单有效。在 VS Code 中，venv 的使用与工作台无缝集成，可以通过图形界面操作，提高效率。

创建和激活 venv 的 VS Code 操作流程

1. 在 VS Code 中打开你的项目文件夹（File > Open Folder）。
2. 打开集成终端（View > Terminal 或 Ctrl+`）。
3. 导航到项目目录（如果需要）：cd /path/to/project。
4. 创建 venv：在终端输入 python -m venv .venv（这会创建一个 .venv 文件夹）。
5. 激活 venv：
   • Windows：在终端输入 .venv\Scripts\activate。
   • macOS/Linux：在终端输入 source .venv/bin/activate。
   • 或者，更方便地使用 VS Code 的 Python 扩展：安装 Python 插件后，在状态栏（左下角）点击 Python 版本，选择“Enter interpreter path” 或从列表中选择你的 venv（通常在项目根目录的 .venv/bin/python）。
6. 安装依赖：在激活的 venv 中运行 pip install -r requirements.txt（如果有 requirements 文件）。VS Code 会自动检测 venv 并在 IntelliSense 中使用正确的依赖。
7. 完成后停用：在终端输入 deactivate，或切换回全局 Python 解释器。
8. 将 .venv 添加到 .gitignore 中，避免将其提交到版本控制。在 VS Code 中，你可以右键文件浏览器中的 .venv 文件夹，选择“Add to .gitignore”。

通过 VS Code 的命令面板（Ctrl+Shift+P），搜索 “Python: Create Environment” 可以图形化创建 venv，进一步简化流程。

使用 unittest 进行测试

Python 的 unittest 模块是内置的测试框架，用于编写和运行测试，确保代码按预期工作。

基本设置

1. 在项目中创建 tests 文件夹。
2. 编写测试文件，例如 test_example.py：

   import unittest
   
   def add(a, b):
       return a + b
   
   class TestAddFunction(unittest.TestCase):
       def test_add_positive(self):
           self.assertEqual(add(2, 3), 5)
   
       def test_add_negative(self):
           self.assertEqual(add(-1, 1), 0)
   
   if __name__ == '__main__':
       unittest.main()
   

3. 在终端运行测试：python -m unittest test_example.py。
4. 自动发现所有测试：python -m unittest discover -s tests。

在 VS Code 中，安装 Python 插件以集成测试浏览器。点击侧边栏的测试管图标来发现、运行和调试测试。

Git 基础

Git 的基本原理

Git 是一个分布式版本控制系统，由 Linus Torvalds 于 2005 年开发，用于管理 Linux 内核的代码。它的核心原理是“快照”而非“差异”：每次提交（commit）都会创建一个完整的项目快照，而不是只记录变更。这使得 Git 高效且可靠。Git 使用“仓库”（repository）来存储项目历史，包括本地仓库（你的电脑）和远程仓库（如 GitHub）。分支（branch）允许并行开发，合并（merge）整合变更。Git 的分布式特性意味着每个开发者都有完整的仓库副本，即使离线也能工作。

为什么使用 Git

• 版本跟踪：轻松回滚到历史版本，避免代码丢失。
• 协作：多人同时工作，通过分支和合并避免冲突。
• 备份与恢复：分布式设计提供多重备份。
• 效率：快速操作，支持大型项目。
• 开源支持：与 GitHub 等平台集成，促进社区贡献。 不使用 Git 会导致手动备份、版本混乱和协作困难，尤其在团队项目中。下载 Git：Git 下载链接。注意在ubuntu上要安装git-lfs：apt-get update && apt-get install -y git-lfs，git lfs install

初始设置

• 从 git-scm.com 安装 Git。
• 配置：git config --global user.name "Your Name" 和 git config --global user.email "your@email.com"。

常用命令

• 初始化仓库：git init
• 克隆仓库：git clone https://github.com/user/repo.git
• 添加变更：git add file.py 或 git add .（所有文件）
• 提交：git commit -m "Commit message"
• 检查状态：git status
• 查看历史：git log --oneline --graph
• 创建分支：git branch new-feature
• 切换分支：git checkout new-feature 或 git switch new-feature
• 合并分支：git merge new-feature
• 拉取更新：git pull origin main
• 推送变更：git push origin main
• 处理冲突：编辑冲突文件，然后 git add 并 git commit。

使用 .gitignore 排除文件，如 .venv/ 或 *.pyc。

在 VS Code 中，源控制视图（Ctrl+Shift+G）提供这些命令的图形界面。

使用 GitHub 进行协作

GitHub 是基于云的 Git 仓库托管平台，非常适合开源和团队项目。它不仅托管代码，还提供问题跟踪、代码审查和自动化工作流。官网：GitHub。在结合 VS Code 的协作中，你可以在 VS Code 中直接克隆仓库、编辑代码、使用插件如 Codex 生成代码，然后通过内置 Git 界面提交变更并推送到 GitHub，实现无缝协作。

入门与发布项目

1. 在 github.com 创建免费账户。
2. 创建新仓库：登录后，点击仪表盘上的“New repository”，输入仓库名称（如 my-project）、描述，选择公开/私有，并可选添加 README.md、.gitignore 和许可证。点击“Create repository”。
3. 发布本地项目（结合 VS Code）：
   • 在 VS Code 中打开终端或使用源控制视图：git init 初始化仓库。
   • 添加文件：git add .。
   • 提交：git commit -m "Initial commit"（或在 VS Code 源控制视图中输入消息并提交）。
   • 添加远程仓库：git remote add origin https://github.com/your-username/my-project.git。
   • 推送代码：git push -u origin main（在 VS Code 中，点击源控制视图的“Publish”按钮）。
4. 管理项目：使用 GitHub 的 Web 界面上传文件、编辑代码，或设置仓库设置如分支保护规则。在 VS Code 中，你可以直接拉取更新（git pull 或点击“Sync”）。

Fork 仓库

Fork 创建仓库的副本到你的账户，用于贡献而不影响原仓库。

1. 转到目标仓库页面，点击右上角“Fork”。
2. 在 VS Code 中克隆你的 fork：打开终端，输入 git clone https://github.com/your-username/forked-repo.git，或使用 VS Code 的“Clone Repository”命令（Ctrl+Shift+P，搜索 “Git: Clone”）。
3. 进行变更、提交并推送至你的 fork：git add .、git commit -m "Changes"、git push origin main（全部可在 VS Code 源控制视图中图形化操作）。

Pull Request（PR）

PR 用于从你的 fork/分支向原仓库提出变更，是参与开源的核心方式。

1. 在 GitHub 上，转到你的 fork，点击“Contribute” > “Open pull request”。
2. 选择 base（原仓库的分支，如 main）和 compare（你的分支）。
3. 添加标题（如“Add new feature”）、详细描述（解释变更、为什么必要、如何测试），并可选链接相关 Issue。
4. 创建 PR。原仓库所有者会审查、评论，你可以根据反馈在 VS Code 中更新代码并推送更多提交。
5. 一旦批准，PR 被合并，你的贡献就融入项目。

如何参与开源项目

开源项目鼓励社区贡献，以下是详细步骤：

1. 寻找项目：在 GitHub 搜索感兴趣的项目（如“python open source”），查看星标（Stars）和活跃度。
2. 阅读指南：检查 README.md 和 CONTRIBUTING.md，了解代码规范、Issue 模板。
3. 处理 Issue：浏览 Issues 标签（如“good first issue”），选择一个。评论“I'd like to work on this” 以避免重复。
4. Fork 和开发：Fork 仓库，在 VS Code 中克隆并在本地分支开发（git checkout -b fix-issue-123 或在源控制视图创建分支）。
5. 测试和提交：确保代码通过测试，提交变更。
6. 创建 PR：如上所述，引用 Issue（如“Fixes #123”）。
7. 互动：响应审查反馈，保持礼貌。合并后，你的贡献会显示在项目历史中。
8. 高级功能：使用 GitHub Actions 设置 CI/CD（如自动测试），或参与 Discussions 讨论想法。在 VS Code 中，你可以使用 GitLens 插件查看详细的协作历史。

使用 Codex 插件进行开发的例子

假设你正在参与一个开源 Python 项目，需要添加一个新功能：实现一个简单的排序算法。首先，在 VS Code 中克隆 fork 的仓库。安装 Codex 插件后，打开一个新文件如 sort.py。

1. 在代码中输入注释提示，例如：

   # Write a function to sort a list of integers using bubble sort
   

2. Codex 插件会自动建议生成代码：

   def bubble_sort(arr):
       n = len(arr)
       for i in range(n):
           for j in range(0, n - i - 1):
               if arr[j] > arr[j + 1]:
                   arr[j], arr[j + 1] = arr[j + 1], arr[j]
       return arr
   

3. 测试代码：在 VS Code 中运行 unittest 或使用调试器验证。
4. 提交变更：在源控制视图中添加文件、提交（消息如“Add bubble sort function”），然后推送至你的 fork。
5. 创建 PR：在 GitHub 上提出变更，描述如何使用 Codex 加速开发，并链接 Issue。

这个例子展示了 Codex 如何在 VS Code 中加速编码，然后无缝集成到 GitHub 协作流程中，提高效率。

GitHub 还提供 Issues 用于跟踪 bug、Projects 用于任务管理，以及 Codespaces 用于云端开发。

结语

当你把 VS Code、venv、Testing、Git、GitHub 这几件事按同一套工程口径串起来之后，本地开发就不再是“在自己电脑上能跑”的偶然事件，而是一种可复现的日常流程：项目目录一打开，解释器明确指向 .venv，依赖来源清晰可追踪；改动发生后，先在 Testing 面板跑相关用例并必要时调试到通过；再用 Git 把变更切成边界清晰的提交；最后通过 GitHub 的分支与 PR，把协作变成可审查、可讨论、可回溯的过程。这样做的直接结果是：环境漂移减少、回归风险前移、沟通成本下降，出了问题也能快速定位到“哪一次提交、哪一个改动、哪一个用例”导致的偏差。

这套链路里最关键的不是工具功能有多全，而是你把“确定性”落在了仓库里：依赖写在 requirements.txt/pyproject.toml，规范落在 .editorconfig 和 .vscode（必要范围内），验证落在 tests/，历史落在 commit 与 PR 的记录里。Codex 这类 IDE 助手可以显著提升编码与重构的速度，但它更适合承担“生成初稿、补齐样板、提出备选实现”的角色；真正决定改动质量的，仍然是测试是否覆盖关键路径、提交边界是否清晰、PR 描述是否能让审查者快速复现与验证。

后续你要进入 Vibe Coding 和 SDD（规范驱动开发）时，这篇文章对应的前置条件可以用一个简单的验收标准来检查：新机器上从零开始 clone 仓库后，在 VS Code 里选中 .venv 解释器，能够一键发现并运行测试；任意一次功能改动都能通过“改代码 → 跑测试 → 提交 → 推送 → PR”这条路径闭环，并且每一步都有可检查的产物（日志、diff、用例、提交记录）。达到这个状态，你的工程就具备了稳定演进的基础。