# Lambda local: rodar e debugar com AWS SAM CLI e VS Code

> Rode uma função Lambda na sua máquina com sam local invoke e debugue com breakpoint no VS Code, antes de subir qualquer código para a AWS.

- Autor: Henrylle Maia, consultor AWS
- Publicado em: 2026-10-15
- Assuntos: Serverless
- URL: https://pages.formacaoaws.com.br/blog/lambda-local-sam-cli-debug-vscode/
- Aula de origem: "AWS Lambda: Como Rodar e Debugar  localmente" (https://www.youtube.com/watch?v=NC_VHHIO3nc)

Rodar uma função Lambda na sua máquina e parar nela com breakpoint, sem subir código para a AWS, dá para fazer com o AWS SAM CLI e o VS Code. A dúvida "como eu rodo e debugo a Lambda local?" aparece cedo para quem começa em serverless, e a resposta tem duas partes: `sam local invoke` para rodar e uma configuração de debug no `launch.json` para parar na linha que você quiser.

> **Importante:** esta aula foi gravada em novembro de 2021, com o SAM CLI 1.34.1 e o runtime Node.js 14. Os passos e a ideia seguem valendo, mas a versão do SAM CLI, os runtimes oferecidos e as telas mudaram. Antes de seguir, confira a documentação atual: [instalar o SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html), [invocar funções localmente com o SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-invoke.html) e [opções de debug do AWS Toolkit for VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/serverless-apps-run-debug-config-ref.html).

## O que você usa e por que

Lambda executa funções sem você alocar servidor: a AWS cuida disso e cobra por milissegundo de uso. Quem começa costuma criar a primeira função no console e, na hora de testar, surge a dúvida de como fazer isso sem publicar a cada ajuste.

A resposta é o **AWS SAM** (Serverless Application Model), o framework da AWS para esse trabalho. Você usa duas peças:

- **SAM CLI**: a linha de comando que cria o projeto e executa a função localmente.
- **AWS Toolkit**: a extensão da AWS para o VS Code, que adiciona a criação da configuração de debug de uma função Lambda.

O SAM executa a função dentro de um container, por baixo dos panos. É essa parte que deixa a execução local parecida com a da AWS.

**Fluxo:** Template SAM (criado com sam init) → Execução local (sam local invoke) → Debug (launch.json com o evento) → Breakpoint (F5 no VS Code) → Conferência (evento e saída no console)

## Passo 1: tenha a função de referência e instale o SAM

Para ter o que comparar, criei antes uma função simples no console da Lambda, com runtime Node.js, que imprime os valores recebidos pelo evento. Testei com o modelo de evento "hello-world" e o console mostrou memória e duração da execução, além dos parâmetros impressos. Vamos ver o mesmo resultado na sua máquina.

Abra uma pasta nova no VS Code e instale o SAM CLI pelo guia da AWS, que tem o processo para Mac, Linux e Windows (link no aviso acima). Eu uso Linux. Depois confirme a instalação:

```bash
sam --version
```

No meu caso, o comando respondeu `SAM CLI, version 1.34.1`. Se ele responder com uma versão, o SAM está pronto.

## Passo 2: crie o projeto com um template

Com o SAM instalado, o comando de início cria a sua primeira função a partir de um template:

```bash
sam init
```

Ele faz algumas perguntas. Na aula, as escolhas foram:

- **template de origem:** `AWS Quick Start Templates`, em vez de um template customizado;
- **tipo de pacote:** `Zip`, em vez de imagem (imagem é para quem trabalha com container);
- **runtime:** `nodejs14.x`, que podia ser qualquer outro da lista;
- **nome do projeto:** `sam-app`, o padrão;
- **template de início rápido:** `Hello World Example`, entre outros disponíveis.

O resultado é a pasta `sam-app` com:

- `events/event.json`: um evento de exemplo;
- `hello-world/`: a função, com `app.js` e `package.json`;
- `template.yaml`: o template que descreve tudo o que o SAM precisa para rodar a função localmente e também para publicá-la na AWS.

No `template.yaml`, o recurso da função se chama `HelloWorldFunction`, com o handler `app.lambdaHandler` e o runtime `nodejs14.x`. Guarde esse nome: é por ele que você chama a função. Abri a pasta `sam-app` em uma nova janela do VS Code para trabalhar só nela.

## Passo 3: coloque o seu código e rode local

Troque o código de exemplo do `app.js` pelo código da função que você quer testar. Na aula, copiei o do hello-world do console e acrescentei um `console.log("Executando funcao local")` para provar que era a execução local:

```javascript
exports.lambdaHandler = async (event, context) => {
  console.log("Executando funcao local");
  console.log("value1 =", event.key1);
  console.log("value2 =", event.key2);
  console.log("value3 =", event.key3);
  return event.key1;
};
```

Nada foi para a AWS. Para executar, dentro da pasta `sam-app`, chame a função pelo nome do recurso que está no template:

```bash
sam local invoke HelloWorldFunction
```

O SAM prepara o container e roda a função. A saída mostra `Invoking app.lambdaHandler (nodejs14.x)`, o que a função imprime e o relatório de execução, com duração, memória configurada e memória máxima usada, bem parecido com o do console da AWS. Como não passei nenhum evento, `value1`, `value2` e `value3` saíram `undefined`.

Para passar um evento, a documentação atual usa `-e` com um arquivo JSON, como o `events/event.json` do projeto: `sam local invoke HelloWorldFunction -e events/event.json`.

## Passo 4: crie a configuração de debug no VS Code

Rodar já ajuda, mas parar dentro do código ajuda mais. Com o AWS Toolkit instalado, o VS Code mostra o atalho **AWS: Add Debug Configuration** acima do `lambdaHandler` no `app.js` (e acima da função no `template.yaml`). Ao clicar, ele abre a lista "Create a Debug Configuration from a CloudFormation Template" com três opções:

- `template.yaml:HelloWorldFunction`, a chamada direta da função;
- `template.yaml:HelloWorldFunction (API Event: HelloWorld)`, a chamada por um evento de API (`GET /hello`);
- `No Template`, que executa a função isolada, sem referenciar um template.

![A lista de opções de debug do AWS Toolkit no VS Code, com template.yaml:HelloWorldFunction, a variante com API Event e No Template](https://pages.formacaoaws.com.br/blog/assets/posts/lambda-local-sam-cli-debug-vscode/debug-opcoes-template.webp)

Escolhi a primeira, a chamada direta. A configuração é gravada no `launch.json` do VS Code, e o campo que interessa é o `payload`: ali você informa os dados do evento que a função vai receber. Como o payload é um JSON, sinalizei isso com `"json"` e escrevi entre chaves os pares que quis:

```json
"invokeTarget": {
  "target": "template",
  "templatePath": "${workspaceFolder}/template.yaml",
  "logicalId": "HelloWorldFunction"
},
"lambda": {
  "payload": {"json": {
    "key1": "valor 1",
    "key2": "valor 2",
    "key3": "valor 3"
  }},
  "environmentVariables": {}
}
```

![O launch.json com o invokeTarget apontando para o template.yaml e o payload com key1, key2 e key3 valendo valor 1, valor 2 e valor 3](https://pages.formacaoaws.com.br/blog/assets/posts/lambda-local-sam-cli-debug-vscode/launch-json-payload.webp)

As três chaves são as que a função lê (`key1`, `key2`, `key3`). Use no `payload` as chaves que a sua função espera.

## Passo 5: coloque um breakpoint e execute

Com o `launch.json` configurado, vá à aba de debug, marque um breakpoint na primeira linha da função (`console.log("Executando funcao local")`) e mande executar. O SAM inicia a execução local e o debugger anexa ("Debugger attached").

Ele para primeiro no início, antes do seu código. Aperte **F5** e a execução chega ao breakpoint dentro da `lambdaHandler`. Abra o `event` no painel de variáveis ou no Watch: estão lá `key1: 'valor 1'`, `key2: 'valor 2'` e `key3: 'valor 3'`, exatamente o que está no `payload`.

![O VS Code parado no breakpoint da linha 19 do app.js, com o event no Watch mostrando key1, key2 e key3 como valor 1, valor 2 e valor 3](https://pages.formacaoaws.com.br/blog/assets/posts/lambda-local-sam-cli-debug-vscode/breakpoint-evento.webp)

Mande continuar a execução e abra o **Debug Console**: lá aparecem os dados impressos pela função, `value1 = valor 1`, `value2 = valor 2` e `value3 = valor 3`, mais o relatório de execução, como se a função rodasse na AWS, só que no seu escopo local.

![O Debug Console depois de continuar a execução, com Executando funcao local e value1 = valor 1, value2 = valor 2 e value3 = valor 3](https://pages.formacaoaws.com.br/blog/assets/posts/lambda-local-sam-cli-debug-vscode/debug-console-saida.webp)

## Checklist

- Instale o SAM CLI pelo guia atual da AWS e confirme com `sam --version`.
- Crie o projeto com `sam init` e escolha o template, o pacote Zip e o runtime que você usa.
- Coloque o código da sua função no `app.js` do projeto criado pelo SAM.
- Rode a função com `sam local invoke` pelo nome do recurso do `template.yaml`.
- Instale o AWS Toolkit no VS Code e crie a configuração de debug com **AWS: Add Debug Configuration**.
- Preencha o `payload` do `launch.json` com o evento que a sua função espera.
- Marque um breakpoint, execute, aperte F5 e confira no Watch se o evento chegou como você definiu.

Rodar e debugar a Lambda na sua máquina encurta o ciclo entre escrever e descobrir o erro. Se você quer aprender serverless e o resto da AWS na prática, do zero ao uso em produção, esse é o tipo de assunto que trabalhamos na Formação AWS.