当前位置：首页 > news >正文

为Github Copilot创建自定义指令/说明/注意事项

news 2025/8/6 1:30:53

GitHub Copilot 是一个强大的 AI 编程助手，通过合理配置自定义指令，可以让它更好地理解和遵循项目特定的编码规范，省的每次提问时输入重复提示语。

方法一：项目级别指令文件（推荐）

1. 创建 `.github/.copilot-instructions.md` 文件

官方文档凌晨：https://copilot-instructions.md/#main-content-zh

在项目根目录创建此文件，如果尚无 .github 目录，则创建该目录。Copilot 会自动读取并作为上下文参考。
文件路径跟是否启用配置项如下，可以直接在vscode中搜索对应选项：
请添加图片描述

2.文件内容示例

# Copilot 代码规范## 通用编程规范### 函数命名规范
- 使用驼峰命名法（camelCase）
- 函数名应该是动词或动词短语
- 布尔值返回的函数使用 is/has/can 前缀#### 示例：
```javascript
// ✅ 正确
function calculateTotalPrice(items) { }
function isUserLoggedIn() { }
function hasPermission(user, action) { }// ❌ 错误
function price(items) { }
function userLogin() { }
function permission(user, action) { }

也可以写一些团队规范，如：

### 组件开发规范
- React/Vue 组件使用 PascalCase 命名
- 组件文件名与组件名保持一致
- Props 使用 TypeScript 类型定义
- 状态管理优先使用内置 hooks### API 调用规范
- 使用 async/await 而不是 Promise.then()
- 统一错误处理机制
- 请求参数使用 TypeScript 接口定义## 项目特定规范### 目录结构约定
- `/src/components` - 可复用组件
- `/src/pages` - 页面组件  
- `/src/utils` - 工具函数
- `/src/types` - TypeScript 类型定义
- `/src/api` - API 接口封装### 样式规范
- 使用 CSS Modules 或 styled-components
- 颜色值使用 CSS 变量
- 响应式设计优先使用 flexbox 和 grid## 代码提交规范### Git Commit 消息格式<type>(<scope>): <subject><body><footer>类型包括：
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式化
- `refactor`: 重构代码
- `test`: 添加测试
- `chore`: 维护任务### 代码审查要求
1. 所有 public 方法必须有 JSDoc 注释
2. 复杂逻辑必须添加内联注释
3. 新增功能必须包含单元测试
4. 性能敏感代码需要性能测试### API 设计原则
- RESTful API 设计规范
- 使用标准 HTTP 状态码
- 响应数据格式统一使用 JSON
- 分页查询统一参数命名

也可以针对特定技术栈创建指令：

# Vue.js 项目指令## 组件开发规范
- 使用 Composition API 优于 Options API
- 组件 props 必须定义 TypeScript 类型
- 事件命名使用 kebab-case
- 组件样式使用 scoped## 状态管理
- 使用 Pinia 进行状态管理
- Store 模块按功能划分
- Actions 使用 async/await## 路由配置
- 路由懒加载
- 路由守卫统一处理权限
- 页面标题动态设置

方法二：VS Code 工作区设置

项目级别设置

在项目根目录创建 .vscode/settings.json：

{"github.copilot.enable": {"*": true,"plaintext": false,"markdown": true},"github.copilot.advanced": {"customInstructions": "遵循项目编码规范：函数使用驼峰命名，组件使用 PascalCase，优先使用 TypeScript 类型定义。API 调用使用 async/await。","inlineSuggestCount": 3},"editor.rulers": [80, 120],"editor.codeActionsOnSave": {"source.fixAll.eslint": true,"source.organizeImports": true}
}

用户级别设置

打开 VS Code 设置（Ctrl+,），在 settings.json 中添加：

{"github.copilot.advanced": {"inlineSuggestCount": 3,"customInstructions": "编写清晰、可维护的代码。优先使用现代 JavaScript/TypeScript 特性。函数命名要有描述性。添加必要的错误处理。"}
}

方法三：代码内注释指令

文件顶部注释

/*** COPILOT: 本文件遵循以下规范* 1. 使用 TypeScript 严格模式* 2. 所有函数必须有类型定义* 3. 错误处理使用统一的 try-catch 模式* 4. 异步操作使用 async/await*/// COPILOT: 用户相关的工具函数集合
export class UserUtils {// COPILOT: 验证用户权限，返回布尔值static hasPermission(user: User, permission: string): boolean {return user.permissions.includes(permission);}
}

内联注释指令

// COPILOT: 创建一个异步函数来获取用户数据，包含错误处理
async function fetchUserData(userId: string): Promise<User | null> {try {const response = await api.get(`/users/${userId}`);return response.data;} catch (error) {console.error('Failed to fetch user data:', error);return null;}
}// COPILOT: 使用防抖优化搜索功能
const debouncedSearch = debounce((query: string) => {performSearch(query);
}, 300);

特定功能指令

<template><!-- COPILOT: 创建一个响应式的用户卡片组件，支持头像、姓名、角色显示 --><div class="user-card"><img :src="user.avatar" :alt="`${user.name}的头像`" class="avatar" /><div class="user-info"><h3 class="user-name">{{ user.name }}</h3><span class="user-role">{{ user.role }}</span></div></div>
</template><script setup lang="ts">
// COPILOT: 定义用户接口类型，包含必要的属性
interface User {id: string;name: string;avatar: string;role: string;email: string;
}defineProps<{user: User;
}>();
</script>

实施建议

1. 优先级排序

项目级别指令文件（.copilot-instructions.md）- 最高优先级
- 被版本控制跟踪
- 团队共享
- 项目特定规范
VS Code 工作区设置（.vscode/settings.json）
- 开发环境配置
- 编辑器行为定制
- 插件配置统一
代码内注释指令
- 文件或函数级别的特定指导
- 临时性指令
- 上下文相关提示

2. 团队协作最佳实践

规范制定流程

团队讨论 - 收集团队成员意见
试运行 - 在小范围内测试规范效果
正式采用 - 将规范纳入项目文档
持续改进 - 定期评估和更新规范

规范执行策略

# 规范执行检查清单## 代码提交前检查
- [ ] ESLint 检查通过
- [ ] TypeScript 编译无错误
- [ ] 单元测试覆盖率满足要求
- [ ] API 文档已更新
- [ ] 性能测试通过## 代码审查要点
- [ ] 函数命名符合规范
- [ ] 错误处理完整
- [ ] TypeScript 类型定义准确
- [ ] 注释清晰易懂
- [ ] 无安全漏洞

3. 监控和改进

指令效果评估

// 定期评估 Copilot 建议质量
const evaluateCopilotSuggestions = {metrics: {acceptance_rate: '建议接受率',code_quality: '生成代码质量',consistency: '规范一致性',productivity: '开发效率提升'},collection_methods: ['开发者反馈调研','代码审查记录分析','自动化质量检测','性能指标监控']
};