# 开发容器最佳实践

`devcontainer` `开发环境` `技能` `Agent`

# devcontainers-best-practices

[![GitHub 最新版本][version-badge]][releases]
[![GitHub 贡献者][contributors-badge]][contributors]
[![MIT 许可证][license-badge]][license]
[![欢迎 PR][prs-welcome-badge]][prs-welcome]
[![约定式提交][commits-badge]][commits]
[![gitmoji][gitmoji-badge]][gitmoji]
[![更新日志][changelog-badge]][changelog]
[![贡献者公约][code-of-conduct-badge]][code-of-conduct]

这是一个 [skills.sh](https://skills.sh/) 技能包，教导 Agent 和开发者**在哪里以及如何**查阅开发容器规范、`devcontainer.json` 参考文档与 Schema、Features、Templates 以及支持 devcontainer 的工具。

## 本技能涵盖内容

- **规范查阅** — 何时使用 [JSON 参考](https://containers.dev/implementors/json_reference/)、[JSON Schema](https://containers.dev/implementors/json_schema/) 和[规范](https://containers.dev/implementors/spec/)。生命周期脚本、`features`、`forwardPorts`、`customizations`、合并逻辑。
- **参考资源** — 规范 URL（containers.dev、devcontainers.github.io）及仓库结构（spec、features、templates、cli、ci）。
- **工具** — [支持的工具](https://devcontainers.github.io/supporting)：VS Code、JetBrains、GitHub Codespaces、Dev Container CLI、DevPod、CodeSandbox 等。各工具特有属性与限制。
- **Features** — [devcontainers/features](https://github.com/devcontainers/features)，OCI 引用（`ghcr.io/devcontainers/features/...`）、版本控制、选项。
- **Templates** — [devcontainers/templates](https://github.com/devcontainers/templates)，何时使用模板、Feature 还是自定义 Dockerfile。
- **最佳实践** — 尽量使用 Features、锁定版本、使用非 root 用户、常用技术栈优先选择官方 Features/Templates。

本技能**面向参考与生态系统**。关于实现模式（Dockerfile、Docker-in-Docker、环境管理），请参阅配套的 [DevContainer Workflow](https://github.com/ilude/claude-code-config) 技能。

## 安装

```bash
npx skills add afonsograca/devcontainers-best-practices
```

如需从其他 fork 或组织安装，使用 `npx skills add <owner>/devcontainers-best-practices` 或[完整 URL 或路径](https://github.com/vercel-labs/skills#source-formats)。

## 更新

CLI 通过来源（如你的仓库）追踪技能。若已安装后需获取最新改进：

```bash
npx skills check   # 查看已安装技能是否有更新
npx skills update  # 将所有已安装技能更新至最新版本
```

无需重新执行 `npx skills add`。重新运行 `add` 同样会刷新本技能，但 `skills update` 才是一次性更新所有技能的推荐方式。

## 仓库结构

本仓库遵循 [Agent Skills 规范](https://agentskills.io/specification) 和 [skills.sh](https://github.com/vercel-labs/skills) 的发现机制。CLI 会在根目录（若存在 `SKILL.md`）或 `skills/` 目录下查找技能。本技能位于 `skills/` 下：

```
skills/
└── devcontainers-best-practices/
    ├── SKILL.md
    └── references/
        ├── spec.md
        ├── schema.md
        ├── tools.md
        ├── features.md
        └── templates.md
```

`SKILL.md` frontmatter 中的 `name` 与目录名（`devcontainers-best-practices`）保持一致。详细参考资料存放于 `references/`，供 Agent 按需加载。

## 相关链接

- [containers.dev](https://containers.dev/) — 开发容器规范与文档
- [devcontainers/spec](https://github.com/devcontainers/spec) — 规范仓库
- [devcontainers/features](https://github.com/devcontainers/features) — 官方 Features
- [devcontainers/templates](https://github.com/devcontainers/templates) — 官方 Templates
- [支持的工具](https://devcontainers.github.io/supporting) — 支持 devcontainer 的工具列表

## 贡献

有意参与贡献？请查阅[贡献指南](CONTRIBUTING.md)了解如何提供帮助。

本项目遵循贡献者行为准则。参与即表示你同意遵守[其条款](CODE_OF_CONDUCT.md)。

## 许可证

本项目采用 MIT 许可证 — 详情请见 [LICENSE](LICENSE) 文件。

## 致谢

本项目由衷感谢：

- [devcontainers](https://github.com/devcontainers) 团队和 [containers.dev](https://containers.dev/) 提供的规范与生态系统。
- [devcontainers/features](https://github.com/devcontainers/features) 和 [devcontainers/templates](https://github.com/devcontainers/templates) 的维护者。
- [skills.sh](https://skills.sh/) / Vercel Labs skills 生态系统提供的 Agent 技能平台。
- [DevContainer Workflow](https://github.com/ilude/claude-code-config) 提供的互补实现指导。
- 所有为本技能做出贡献或使用本技能的人。

<!-- badges -->

[version-badge]: https://img.shields.io/github/v/release/afonsograca/devcontainers-best-practices?sort=semver&style=flat-square
[releases]: https://github.com/afonsograca/devcontainers-best-practices/releases
[contributors-badge]: https://img.shields.io/github/contributors/afonsograca/devcontainers-best-practices?style=flat-square
[contributors]: https://github.com/afonsograca/devcontainers-best-practices/graphs/contributors
[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[license]: LICENSE
[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs-welcome]: http://makeapullrequest.com
[commits-badge]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white&style=flat-square
[commits]: https://conventionalcommits.org
[gitmoji-badge]: https://img.shields.io/badge/gitmoji-%20😜%20😍-FFDD67.svg?style=flat-square
[gitmoji]: https://gitmoji.dev/
[changelog-badge]: https://img.shields.io/badge/changelog-Keep%20a%20Changelog-orange?style=flat-square
[changelog]: CHANGELOG.md
[code-of-conduct-badge]: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=flat-square
[code-of-conduct]: CODE_OF_CONDUCT.md